初始化项目

模板本身是空的。这个技能的任务是通过提问把它变成一份准确的项目手册——问完之后，一个半年后第一次进来的 agent 应该只读 AGENTS.md 就能正确干活。

产出质量取决于问题质量。宁可多问两轮，也不要靠猜填占位符。

访谈原则

这几条决定了访谈是好用还是折磨人：

1. 一次问 3~5 个，不要一次抛 20 个。 问完一组、得到回答、落盘，再问下一组。
2. 每个问题都给推荐答案。 让用户能直接说"就用默认"。开放式问题（"你想怎么设计？"）会让用户卡住，带选项的问题（"A 还是 B，我建议 A 因为……"）不会。
3. 不问能自己看出来的。 见阶段 0。问用户 package.json 里写着的东西会立刻消耗掉他的耐心。
4. 用户说"不知道 / 你决定"时，不要卡住。 给出你的选择 + 一句理由，标注为「agent 代填，待确认」，继续往下走。
5. 答案模糊就追问一次。 "要好用"、"性能要好"这种答案不可执行，追问："能给个具体场景吗？比如什么情况下你会觉得它不好用？"
6. 每阶段结束立刻落盘。 用户可能随时中断，写进文件的才算数。
7. 只记录模型猜不到的东西。 用户的口径选择、历史包袱、被否决的方案、项目特有的陷阱。不要把"要写测试"、"注意错误处理"这类模型本来就知道的内容写进产出。
8. 用推导式提问，少用清单式。 能从上一个答案推出来的问题，就说明推导过程再问——"你说这是单用户本地工具，那我推断没有登录鉴权；下一个问题：数据存哪？因为这决定本地文件还是嵌入式数据库。"清单式提问（把题库念一遍）让用户觉得被审问，推导式让他觉得被理解，也让误解在早期暴露。

流程

- [ ] 阶段 0：生成骨架 + 勘察现状（不问用户）
- [ ] 阶段 1：项目定位（6 个必答）
- [ ] 阶段 2：领域深挖（按形态分支）
- [ ] 阶段 3：红线与口径
- [ ] 阶段 4：范围边界
- [ ] 阶段 5：落盘、体检、复述确认

每个阶段结束跑一次收敛自检——只要下面四条都能回答，就不必按部就班走完所有阶段，直接进阶段 5 落盘：

• 能一句话说出项目做什么、给谁用
• 能说出可验证的成功标准
• 能说出第一个任务的完整执行上下文（入口、数据、红线）
• 阶段 3 的红线与口径六问都已问过（用户答"没有"也算问过；没问过就不可能"没有未决问题"）

四条不全通过，就继续下一阶段。问题数量由内容决定，不由流程决定——问够了就停，没问够就继续。

轻量档：先问 3 个就开工

完整流程是给"要长期维护、别人也会用"的项目准备的。周末小工具、一次性脚本、还不确定做不做得成的试验，第一次接触就被问三十道题只会让人放弃。这种情况先走轻量档，在阶段 0 之后直接问这 3 个：

1. 一句话说清做什么、谁用（阶段 1 问题 1）
2. 做到什么程度算成功（阶段 1 问题 2）
3. 从零到能跑起来、以及验证改动对不对，分别跑什么命令（阶段 1 问题 5）

轻量档只保留和具体功能实现相关的问题，不额外问敏感数据与红线，也不建议换完整版。

落盘时和完整流程一样删掉 AGENTS.md 顶部的「这个仓库还没初始化」引用块，但保留同一个 TODO(init) 欠账标记：没问到的占位符改写成 TODO(init): 轻量初始化未覆盖——/ship-change 首次碰到时现场追问再补。体检脚本会把 TODO(init) 报为 warning（不是"未初始化"的硬错误），其中轻量欠账单独计数，和「完整初始化没做完」区分开：完整初始化的完成线仍是 TODO(init) 归零，轻量档则是有意保留欠账。之后每次 /ship-change 碰到与本次改动相关的 TODO(init)，当场问一句补上；与本次改动无关的欠账不要顺手全补。

阶段 0：生成骨架 + 勘察现状

先生成骨架，再看现状。 本技能自包含一套项目骨架模板（templates/，与 SKILL.md 同目录）。先确认 Node 可用（脚手架和体检脚本都是零依赖 Node 脚本）：

node --version

先确认技能挂载，再生成骨架。 scaffold.mjs 只生成 12 个骨架文件，不安装技能；项目根没有 .agents/skills/ 时，初始化完成后 /ship-change、/maintain-context 不会被宿主发现。先用 dry-run 拿到项目根并预览：

node <与 SKILL.md 同目录>/scaffold.mjs --dry-run [--root <项目根>]

它打印的「项目根：…」就是后续所有步骤的根。按这个根检查技能挂载：

• <项目根>/.agents/skills/init/SKILL.md 存在 → 项目级技能已挂载，继续。
• 不存在，但本技能自身路径在全局技能目录下（如 ~/.dsh/skills/、~/.codex/skills/）→ 全局技能已覆盖本项目，和用户确认「用全局技能，不复制进项目」后继续（全局和项目级二选一，不要两处都装）。
• 不存在，且本技能也不在全局目录（例如你在另一个仓库里运行 init）→ 停一下，把本技能所在的 skills 目录整套复制到 <项目根>/.agents/skills/，确认 init、ship-change、maintain-context 等目录都在，再继续：

mkdir -p <项目根>/.agents/skills
cp -r <本技能所在 skills 目录>/* <项目根>/.agents/skills/

确认挂载后，再正式生成骨架。scaffold.mjs 会把骨架（AGENTS.md、docs/、scripts/、.agents/evals/、.gitignore）生成到项目根（最近的 .git 祖先，没有就用当前工作目录），且只创建缺失文件、绝不覆盖已有的。唯一例外：“Use this template” 复制出的新仓库里，根 AGENTS.md 是框架维护者手册（带 FRAMEWORK-AGENTS 标记）、README 还带着 FRAMEWORK-README 标记时，脚手架会受控替换这份 AGENTS.md；你自己的 AGENTS.md 没有框架标记，绝不覆盖：

node <与 SKILL.md 同目录>/scaffold.mjs [--root <项目根>]

--root 显式指定项目根（monorepo 子目录、尚未 git init 时用它）；--dry-run 只预览将新建/跳过哪些文件，不写入。

脚手架是单一宿主设计：只生成一份 AGENTS.md + 一份 .agents/（不生成任何镜像副本）；docs/、scripts/、.gitignore 也由脚手架一并补齐。

本技能后续所有步骤里的 AGENTS.md、docs/、scripts/ 都指项目根目录（scaffold 生成后的位置）。

然后先看，再问。动手前把这些读一遍，把已经能确定的信息填好，只对读不出来的部分提问：

• 目录结构（有没有已存在的源码）
• 包管理文件：package.json / pyproject.toml / Cargo.toml / go.mod / pom.xml 等——语言、框架、依赖、脚本命令都在这里
• README.md（模板自带的那份不算）
• CI 配置：.github/workflows/、.gitlab-ci.yml。若仓库仍带 FRAMEWORK-README 标记，context-dev 自带的 tests/context-scripts.test.mjs 与 .github/workflows/ci.yml 只验证上下文框架，不算项目代码的 CI
• git log：如果是接管已有项目，最近的提交能看出在做什么

然后告诉用户你看到了什么，让他确认或纠正：

我看了一下仓库，这是一个空项目 / 已有一个用 X 写的 Y。下面几个问题是我从代码里看不出来的。

阶段 1：项目定位（必答）

这 6 个问题决定后面所有分支，必须问完。

1. 一句话说清这个项目做什么，谁会用它？（只有你自己用 / 小团队 / 对外发布——这决定要不要写面向他人的文档和向后兼容约束）
2. 做到什么程度算成功？ 给一个能验证的标准，不要"做得好用"。比如"能把 A 格式的文件转成 B 并且我每周真的在用"。
3. 技术栈和运行形态？ 语言、框架，以及跑起来是什么东西：Web 应用 / API 服务 / CLI 工具 / 库或 SDK / 数据分析或批处理 / 机器学习训练 / 自动化脚本集 / 桌面应用。
4. 会碰到敏感数据吗？ 个人信息 / 生产数据 / 密钥凭证 / 完全没有。这一条决定隐私红线的强度，不要跳过。
5. 怎么验证代码是对的？ 测试、类型检查、lint、构建的命令各是什么？还没有的话，想用什么工具？以及验证范围：每次改动跑相关命令就够，还是每次都要跑全量？（默认"相关命令就够，全量留给里程碑/发版前"，倾向全量兜底时把默认覆盖掉）
6. 全新项目，还是接管已有代码？ 接管的话，有哪些历史包袱是你希望 agent 一开始就知道的？

回答完立刻落盘，再进阶段 2。这六个答案分散在四个文件里，按 references/output-map.md 归位——问题 1、2、6 进 docs/goals.md，问题 3 进 docs/architecture.md，问题 4 进 AGENTS.md 铁律和 .gitignore，问题 5 进 AGENTS.md 命令表（每条命令都要真的跑一遍再写进去），其中「验证范围」这半问任意时刻只写一份：留了铁律 2「改完自己跑与改动相关的验证命令」就只写在那条铁律里；删掉铁律 2 时才把口径补进命令表上方那句说明。两处都写会漂——改一处忘另一处，agent 读到互相矛盾的两句话。

阶段 2：领域深挖

先问题库开头的 references/question-bank.md「通用追加组」5 问（自主程度、提交与分支、风格由工具还是人、CI、多久重拾一次）——它们决定 agent 的行为方式，和项目形态无关，每个项目都要问。

再按问题 3 的答案选形态分支，从同一份题库里取对应的问题组。

题库按形态分了七组（Web / API、CLI、数据流水线、库 SDK、机器学习、自动化脚本、通用兜底），每组 5~9 个问题。读题库，挑真正适用的问，不要机械念完——不适用的问题跳过并说明为什么跳过。

如果用户的项目跨了两个形态（比如"一个带 CLI 的库"），两组都取，去掉重复的。

当项目是面向用户的产品时（Web 应用、App，或任何需要做「功能 → 界面」设计的产品形态），在形态分支问完后调用 product-design 技能做一次契约访谈：把每个功能收敛成「一个问题 → 一个输出 → 一个决定」，并用它的过滤问题清一遍范围。收敛出的功能契约与「明确不做」一并落进 docs/roadmap.md 的「明确不做」和 docs/goals.md。

契约访谈默认先做「外部基准」：先看同类产品如何回答同一个问题，再确认契约三行。用户的初始构想是起点不是终点——避免个人框架锁死设计空间。

本阶段答案按 references/output-map.md 立刻落盘（架构、术语、坑分别进 docs/architecture.md、docs/glossary.md、docs/troubleshooting.md），不要攒到阶段 5。docs/architecture.md 的「关键组件」「数据模型要点」「关键取舍」：访谈时用户已有设想就写下来，没有就明确留空、标注由 /ship-change 后续补——不要靠猜填。

阶段 3：红线与口径

这一层最容易被略过，但它恰恰是模板长期价值的来源——因为这些信息在代码里读不出来。

1. 有没有绝对不能碰的文件、目录或环境？（生产配置、别人维护的模块、自动生成的代码）
2. 有没有必须遵守的外部约束？（公司规范、合规要求、上游 API 的配额或速率限制、许可证）
3. 有没有你已经否决过的方案，不想被反复提议？ → 每一条都写成 ADR。
4. 有没有踩过的坑，想让 agent 一开始就知道？（环境问题、某个库的陷阱、某个操作会静默失败）→ 写进 docs/troubleshooting.md。
5. 项目里有哪几个词，不同的人叫法不一样？ 或者哪个词在你这里有特殊含义？→ 写进 docs/glossary.md。
6. 有没有什么错误是 agent 已经犯过、你不想它再犯的？ → 这是最有价值的规则素材，写成 AGENTS.md 的一条铁律，带 ❌/✅ 对照。

答完立刻落盘：问题 1、6 进 AGENTS.md 铁律，问题 6 的每条答案同时在 .agents/evals/behavior-cases.md 补一条用例；问题 2 进 docs/goals.md「约束」，不是红线的别往铁律里塞。顺带把 AGENTS.md 自带的三条可选铁律（验证范围、范围纪律、决策留痕）过一遍，问用户留哪些——三条不可逆或不可发现的红线不必问，默认保留。

阶段 4：范围边界

1. 第一个里程碑（M1）是什么？ 拆成 3~6 个可交付的条目。
2. M2、M3 只写方向，不拆细。 拆了也会改——提前拆是在为还不存在的需求做设计，后续里程碑留给演进引擎补。
3. 明确不做的事有哪些？ 追问一句："有没有什么功能，听起来很自然但你确定不要？"——防止 agent 自作主张扩张范围。
4. 当两件事冲突时你倾向哪边？ 快速可用 vs 长期可维护、功能覆盖 vs 简单可靠、自动化程度 vs 可控可审查——这三组对应 docs/goals.md 的「优先级取舍」表。
5. 现在优先做哪一个？

写入 docs/roadmap.md；第 3 条的答案同时落 docs/roadmap.md「明确不做」和 docs/goals.md「明确不追求」，第 4 条落 docs/goals.md「优先级取舍」。

阶段 5：落盘、体检、复述

1. 按 references/output-map.md 把所有答案写进对应文件。每个答案都有明确的归属，不要把什么都堆进 AGENTS.md。
2. 删掉 AGENTS.md 顶部的「这个仓库还没初始化」引用块。
3. README.md：带 FRAMEWORK-README 标记的那份整份重写。 它讲的是 context-dev 框架不是你的项目，而这是任何人打开仓库看到的第一份文件。换成这个项目的：一句话简介、怎么装怎么跑、目录结构，连同标记一起删掉。没有这个标记，说明 README 是用户自己的，不要重写——只在缺「怎么装怎么跑」时补上。
4. 按项目形态创建源码和测试目录，更新 AGENTS.md 的目录地图。若这是从 context-dev 模板创建的新仓库，同时补上项目代码自己的验证命令与 CI；框架自带的冒烟测试可以保留，但不能代替项目验证。
5. 更新 .gitignore。 逐类过一遍，不要只看一眼就跳过：
   • 依赖目录（node_modules/、.venv/、vendor/）
   • 构建产物（dist/、build/、.next/、target/）
   • 生成的代码（ORM client、protobuf、next-env.d.ts）——最容易漏
   • 本地数据库与运行时数据
   • 密钥与本地配置，以及阶段 1 问题 4 提到的一切
6. 跑体检：

node scripts/audit-context.mjs

把它报的 error 全部修掉，warning 逐条判断。完整初始化要求 TODO(init) 归零——还有残留就说明访谈没做完，回去补问，不要自己编一个填上。轻量档会保留带「轻量初始化未覆盖」的 TODO(init)，那是合法的欠账，由 /ship-change 按需补齐；不要为了凑零而把它们改成“已完成”。

7. 最后向用户复述，用一段话，不要用列表：

我理解你要做的是 ⟨项目一句话⟩，成功标准是 ⟨可验证的标准⟩。技术上用 ⟨栈⟩，最需要小心的是 ⟨红线⟩。接下来先做 ⟨第一个里程碑⟩，明确不做 ⟨排除项⟩。哪里理解错了？

复述是最后一道防线。用户看到被误解的地方会立刻纠正，而这些误解如果留在 AGENTS.md 里，会持续误导后面每一次对话。

中断与续问

用户随时可能停下。恢复的办法是搜索残留标记，不需要额外的状态文件：

node scripts/audit-context.mjs

脚本会列出还有哪些文件带 TODO(init)。先复述你目前的理解（项目做什么、已定的口径和红线），让用户纠偏，再从最靠前的那个未决问题所属的阶段接着问。

完成之后

AGENTS.md 顶部没有「这个仓库还没初始化」引用块、且 TODO(init) 归零时，完整初始化即完成。轻量档完成后引用块同样删掉、但会保留带「轻量初始化未覆盖」的 TODO(init)——那是欠账，不是未初始化。init 技能可以留着——它靠引用块触发，不靠 TODO(init) 残留触发，所以轻量档的欠账不会每轮都误触发 init；如果你要拿这个仓库继续孵化别的项目，也正需要它。

后续维护交给 /maintain-context。