如何让 Claude Code 稳定长跑

一、核心开关 & 行为约束

markdown 复制代码

# Project Operating Mode

- Goal: 完成【<你的长程任务名称>】，在**不中断**的前提下，充分并行子任务，直到产出完整、可验证的交付物。
- Autonomy: 允许在本仓库内创建/修改/删除文件；禁止写入 `node_modules`, `.git`, `dist`, `build`, `~` 与上级目录。
- Parallelism: 同时运行 ≤ <N> 个并行任务（可弹性：队列剩余任务排队）。
- Edit Policy: 默认使用"Auto-accept plan"（先给出计划，随后自动执行，无需逐步确认）。
- Checkpointing: 每轮重大变更后，**必须**更新 `PLAN.md` 与 `TASKS.md`，以便断点续跑。
- Validation First: 任何子任务完成后，都要跑对应校验（构建/测试/脚本），不通过则自我修复后再进入下一个任务。

官方强调把"规则/分工/节奏"写进 CLAUDE.md 并不断迭代；将其视作高频提示词而非一次性说明书。

二、并行调度与任务分片

markdown 复制代码

# Parallel Work Orchestration

## Work Decomposition
- 将目标拆成可并行的最小工作单元（WUs），每个 WU ≤ 20 分钟理想工时。
- 对每个 WU 明确：输入、产出、校验方式、完成定义(DoD)。

## Parallel Policy
- `MaxParallel = <N>`：任意时刻最多并行 N 个 WU。
- 优先级：阻塞链路优先（解开关键路径），IO/计算重任务交错布置。
- 队列：若待办 > N，则将其入队，先短任务、后长任务（SJF 优先策略可加速整体吞吐）。

## Subagents / Tasks
- 对每个 WU 启动一个"任务 Agent"（Task），保持相互独立的上下文与日志文件：`/logs/task-<id>.md`。
- 每个 Task 都必须在结束时写入：
  - `RESULTS/<id>.md`（产出与结论）
  - `PATCHES/<id>.diff`（文件变更集）
  - 更新 `TASKS.md` 的状态（TODO → DOING → DONE）

利用 Task/子代理实现真正并行，并按并发上限运行与排队

三、长程任务"不断点"运行策略（自我复位 + 断点续跑）

markdown 复制代码

# Long-Run Resilience

## Checkpoint Files
- `PLAN.md`: 总体路线图 + 关键里程碑 + 风险与对策（每次大改必须更新）
- `TASKS.md`: 任务清单（含优先级、预计时长、并行槽位分配、状态）
- `RISKS.md`: 风险项台账（触发条件、预案、回滚点）
- `METRICS.md`: 每轮产物质量指标（测试覆盖率、构建时长、性能基线等）

## Resume Protocol (when session restarts)
1) 打开 `PLAN.md` / `TASKS.md`，识别未完成项与最新 Checkpoint。
2) 如果检测到构建/测试红灯，先进入"修复模式"，直至绿灯。
3) 恢复并行队列：按 `TASKS.md` 重新分配 `MaxParallel` 槽位，继续执行。

将"可恢复的工作清单"写进项目文件，让模型每次启动都能自发现上下文并续跑

四、质量闸口（构建/测试/验收定义）

markdown 复制代码

# Validation & Definition of Done (DoD)

- 对每个 WU 必须定义可执行的验收脚本（例如 `npm run test:<scope>`、`pytest -k <marker>`）。
- 进入下一任务前，必须满足：
  - 构建通过
  - 测试通过（新增测试覆盖新代码路径）
  - Lint/Format 通过
  - 若涉及接口/前端：提供最小可运行 Demo 或截图/录屏证据，附在 `RESULTS/<id>.md`。
- 不通过→自修复（最多 2 次），仍失败则降级/回退并记录在 `RISKS.md`。

为什么重要？ 长程并行任务若无清晰 DoD，容易"并行空转"或积累技术债。

五、权限与"自动批准"实践（减少打断）

markdown 复制代码

# Permissions & Safety

- 默认在本项目根目录工作；禁止访问上级目录及系统目录。
- 允许对以下路径写入：`src`, `tests`, `scripts`, `docs`, `public`, `infra`, `configs`。
- 若需写入新目录，必须先在 `PLAN.md` 提案并解释用途，再执行。

六、组织你的仓库（方便 Agent 自管理）

bash 复制代码

/docs/CLAUDE.md          ← 本文件
/docs/PLAN.md            ← 路线图 + 里程碑
/docs/TASKS.md           ← 并行任务看板（队列/状态/优先级）
/docs/RISKS.md           ← 风险与回滚点
/docs/METRICS.md         ← 质量指标与历史
/logs/task-*.md          ← 子任务日志
/RESULTS/<id>.md         ← 子任务产出说明
/PATCHES/<id>.diff       ← 变更集

把"任务编排元数据"显式文件化，Claude Code 重启即可"看文件行事"，这是很多长程项目能坚持"不中断推进"的关键。