Large Project Pipeline

Overview

大型项目的失败模式不是"写不出代码"，而是需求含糊就开工、约束只存在于对话里、进度无人可查、质量没有门禁。本 Skill 把需求决策、项目约束、进度状态、质量凭证四件事全部外置到磁盘文件，用脚本做确定性门禁：需求没对齐不许开工，阶段测试没通过不许收工。

核心机制：任何"完成"都必须有磁盘上的证据，且由脚本判定，不由模型自述。

---

何时使用

使用：

• 用户要构建/重写一个非平凡项目（多文件、多模块、需要分阶段交付）
• 用户要求"先出方案再写代码""分阶段做""每阶段测试通过再继续"
• 用户要求生成 RULES.md / PLAN.md，或要求"边做边记下易错点"
• 项目需要跨多次会话完成

不使用：

• 单文件脚本、单次小改动、纯问答、代码解释
• 已有明确详细规格且规模很小的任务

---

落盘四件套（本 Skill 的契约）

<项目根>/
├── REQUIREMENTS.md   # 需求与决策记录：需求要点、范围边界、决策记录、待确认假设、未闭合阻塞项
├── RULES.md          # 项目规则与易错点：项目契约、Pitfalls、红线
├── PLAN.md           # 唯一进度事实源：阶段分解 + 任务勾选 + 证据指针 + 汇总
└── tests/
    ├── README.md
    └── phase{N}_{名称}/
        ├── test_*_          # 阶段测试代码
        └── RESULT.md        # 运行记录，末尾必须有 `结论：PASS` / `结论：FAIL`

四件套的权威性：磁盘文件 > 本轮对话 > 你的记忆。冲突时以文件为准，并以实际运行结果裁决。

---

铁律（违反即流程失效）

1. 需求未对齐不得开工。 check_requirements.py 退出码不为 0 时，只能去追问或声明自主决策，不能写业务代码。
2. 每个阶段必须测试通过才能收工。 check_phase.py 退出码不为 0 时，不许宣布阶段结束、不许进入下一阶段。
3. 每条 - [x] 必须带证据指针：- [x] 任务 → 文件:行号 · 测试用例名。没有证据的勾选视为未完成。
4. 禁止整段重写 PLAN.md。 只允许增量追加、勾选、用 sync_plan.py 改状态。
5. 禁止用删除/注释/skip 失败用例、篡改 RESULT.md、--force/--no-verify 来绕过门禁。 失败就修实现。
6. 追问必须带选项与推荐。 不许问"你想要什么样的"这类无选项问题；不许问能从代码库读到的事实。
7. 每阶段开工前先读文件状态，收工前先更新文件状态。

---

工作流

S0 需求对齐 → S1 初始化 → S2 RULES.md → S3 PLAN.md → S4 阶段循环（×N） → S5 收尾
                                ↑                          │
                                └──────────────────────────┘

S0 需求对齐（阻塞式，最多 3 轮追问）

目标：把含糊需求变成可执行的决策，产出 REQUIREMENTS.md。

1. 先自助：项目里已有的代码、配置、文档、依赖清单，自己读，不问用户。
2. 抽决策分支（3–6 条，按依赖顺序）：目标与成功标准 → 交付形态 → 技术栈与依赖 → 数据与存储 → 接口与鉴权 → 规模与性能 → 范围边界。
3. 结构化提问：每轮 1–4 题，每题必须给出 2–4 个具体选项 + ⭐推荐 + 代价说明 + "你来定"出口。问完等回答，不许自问自答。
4. 按级别处理（详见 references/requirement-interrogation.md）：
   • 🟥 阻塞：不问清无法动手 → 必须得到答案
   • 🟨 重要：有合理默认值 → 用默认值继续，登记进 REQUIREMENTS.md §4 待确认假设
   • 🟩 次要：记入 PLAN.md 待定项，做到相关阶段再问
5. 用户不配合时（连续 2 轮不答 / 说"你决定" / 已达 3 轮上限）→ 切自主决策模式：自行拍板全部 🟥 项，写入决策记录并标注"未经用户确认"，同时在第一个阶段开头列出「需用户复核的决策」。
6. 落盘并过门禁：

   python scripts/check_requirements.py --root <项目根>
   

   退出码 0 才允许进入 S1；否则继续追问。

S1 初始化

python scripts/init_project.py --root <项目根> --lang python|node|go|rust|generic [--test-cmd "..."] [--smoke-cmd "..."]

• 幂等：已有文件默认跳过，不覆盖内容。
• 退出码 2 = 同名文件冲突：说明项目根已有非本流程生成的 RULES.md/PLAN.md。此时禁止覆盖，必须向用户提问：A) 复用该文件只追加；B) 改用带前缀的名字（AGENT_RULES.md）；C) 四件套收进 .pipeline/。

S2 生成 RULES.md

• 从 references/pitfall-library.md 挑 8–15 条与本项目技术栈相关的条目，不要整篇复制。
• 必填"项目契约"表：测试命令、冒烟命令、目录约定、禁止引入的依赖。
• 规则必须可执行：写"循环里不要逐条查库，改批量接口"，不写"注意性能"。
• RULES.md 是错题本，之后每阶段踩的坑都要追加。

S3 生成 PLAN.md

• 按依赖顺序拆阶段，方法见 references/phase-decomposition.md。单阶段预算：≤ 300 行改动 / ≤ 5 文件 / 单次会话可完成。
• 每阶段必须写：目标、涉及文件、对外接口/契约、验收标准、任务清单、测试目录、已知风险。
• 先写契约，再写测试，最后写实现。
• 阶段划分必须得到用户确认后才开始执行。

S4 阶段循环（核心，不可跳步）

1. 读：REQUIREMENTS.md（相关决策）+ RULES.md + PLAN.md 当前阶段段落。
2. 做：按契约实现。
3. 测：在 tests/phase{N}_{名称}/ 写测试：至少 1 条正例、1 条失败路径、1 条边界值；断言具体值。
4. 跑：跑本阶段测试 → 通过后跑冒烟集（防回归延迟爆发）。失败就修实现；同一问题重跑上限 3 次，超限停下向用户汇报根因与选项。
5. 记：把命令、结果、失败修复记录写入 RESULT.md，末尾写 结论：PASS。
6. 勾：更新 PLAN.md 任务勾选，每条补证据指针。
7. 学：本阶段踩的坑追加进 RULES.md。
8. 交（门禁）：

   python scripts/check_phase.py --root <项目根> --phase N --require-smoke
   python scripts/sync_plan.py   --root <项目根> --phase N --status done --next "..."
   

   退出码非 0 → 不许进入下一阶段。
9. 提醒：若 REQUIREMENTS.md 有 ❗ 待确认假设，列出来请用户复核。

S5 收尾

• 跑全量测试（tests/ 全部），不只跑最后一个阶段。
• 检查 PLAN.md「未完成」区块为空或已明确说明，风险项逐条列出，不许隐瞒遗留问题。
• 检查 README 的用法示例与实际命令一致（常见遗漏）。

---

收工六项（Definition of Done）

每阶段收工前逐项确认，缺一项就不能收工：

• 实现完成，且与契约一致
• 新增测试通过（含失败路径与边界值）
• RESULT.md 已记录命令与结论
• PLAN.md 任务已勾选、证据指针已补、汇总已更新
• 本阶段新坑已追加进 RULES.md
• README / 用法示例已同步

---

必须停下来问用户的触发器

出现以下任一情况，立即暂停，用 S0 的提问格式（选项 + ⭐推荐）向用户确认，不许自行决定：

• 需要新增第三方依赖
• 要修改数据库 schema 或对外接口契约
• 需要用户提供凭据、付费服务或外部账号
• 发现需求内部自相矛盾
• 同一个问题修 3 次仍不通过
• 需要改动 REQUIREMENTS.md 里已确认的决策（走变更流程：回写变更日志 + 影响面分析 + 用户确认）
• 发现已完成阶段的产物需要返工

---

恢复协议（跨会话/上下文压缩后的第一步）

先读文件、再验证、再确认、最后动手。 完整协议见 references/recovery.md。

python scripts/check_requirements.py --root <项目根>
python scripts/check_phase.py --root <项目根> --phase <上一阶段> --require-smoke
python scripts/sync_plan.py   --root <项目根> --report

然后跑一次冒烟测试，用一句话复述「当前阶段 / 下一步」，等用户确认后再动手。

绝不凭记忆重新实现已有功能；PLAN.md 说完成但没有 RESULT.md/证据的，一律视为未完成。

---

反模式（明确禁止）

---

资源索引

scripts/

所有脚本均为 Python 标准库实现，无第三方依赖，兼容 Windows（显式 UTF-8）。

references/

assets/templates/

REQUIREMENTS_TEMPLATE.md · RULES_TEMPLATE.md · PLAN_TEMPLATE.md · TEST_RESULT_TEMPLATE.md · TESTS_README_TEMPLATE.md

由 init_project.py 自动复制并填充占位符（{{LANG}}、{{TEST_CMD}}、{{SMOKE_CMD}}、{{DATE}}、{{PROJECT_ROOT}}）。手动补文件时也从这里复制，保持格式一致。

---

首次使用检查清单

• 已跑 init_project.py，四件套就位（或已就冲突项询问用户）
• REQUIREMENTS.md 通过 check_requirements.py
• RULES.md 的项目契约表填了测试/冒烟命令
• PLAN.md 阶段划分已获用户确认，每阶段有契约与验收标准
• tests/README.md 写清了本项目的三档测试命令