context-dev — Agent 工作手册

这是框架本身的仓库，不是用它初始化出来的项目。 .agents/skills/ 是完整版产品——五个要被安装到别人项目里的技能；lite/ 是轻量版发行包——两个技能 + 四个骨架文件，供个人 / 中小型项目长期迭代使用。两者里的 templates/ 都是产出物，是别人项目的起点。把它们当成本仓库的配置来改，是这里最容易犯、也最贵的错。

本文件不会被两份 scaffold.mjs 中的任何一份复制到别处（它们只复制各自的 templates/）；但 GitHub Template 会把它复制进新仓库，此时 scaffold.mjs 会识别上面的 FRAMEWORK-AGENTS 标记并在 README 仍带 FRAMEWORK-README 标记时受控替换。改它只影响在本仓库里干活的 agent。

快速上手

零依赖，无需安装，只要 Node 20+（CI 固定 20）：

node --version
node --test

验证命令（改完代码必须自己跑，不要让用户当第一个发现问题的人）：

语法检查里的三个文件、体检仓库根和 node --test 合起来就是 .github/workflows/ci.yml 的全部内容，没有额外的全量档。

体检脚本本身已被 node --test 覆盖，手动跑只是为了看输出。不带 --root 时 ROOT 由脚本自身位置推导，所以检查的是 templates/ 子树而不是仓库根；--root . 才会体检本仓库根。模板树的合格状态是「0 error、若干占位符 warning」——占位符是 warning 不是 error。仓库根体检的「缺少 docs/learning-inbox.md」warning 是预期：根目录按铁律 4 不补 docs/，学习闭环只存在于 templates/ 生成的用户项目里。因此 /ship-change 第 7 步在本仓库没有收件箱可写：蒸馏信号直接并入本文件或 README，不要创建 docs/。

目录地图

AGENTS.md                本文件。每次对话全量加载
.agents/skills/          完整版产品：五个技能，完整版唯一需要安装到用户项目的东西
  init/SKILL.md          分阶段访谈流程（含轻量档）
  init/scaffold.mjs      把 templates/ 生成到用户项目根
  init/references/       访谈题库与答案落盘映射，按需加载
  init/templates/        完整版骨架模板 —— 产出物，不是本仓库的配置
lite/                    轻量版发行包：init + maintain 两个技能、四个骨架文件
  README.md              轻量版安装与用法，完整版 / lite 二选一
  scaffold.mjs           把 lite/templates/ 生成到用户项目根
  skills/                两个轻量技能，安装到用户项目 .agents/skills/
  templates/             轻量骨架模板 —— 产出物，不是本仓库的配置
tests/                   scaffold 与 audit 的冒烟测试，脚本的行为边界以它为准
.github/workflows/ci.yml 语法检查 + node --test
README.md                对外说明书，带 FRAMEWORK-README 标记（初始化时被整份替换）

铁律

前五条是这个仓库特有的，违反了会让产品对所有用户出错，而且从代码里读不出来。

1. 不在本仓库运行 /init，也不运行不带 --root 的 scaffold.mjs——完整版和 lite/scaffold.mjs 都算。 前者会把 12 个完整骨架、后者会把轻量骨架写进仓库根，和各自的 templates/ 树混成两套同名文件，之后没人分得清哪份是产品、哪份是配置。要试脚手架就用 --dry-run 或 --root <临时目录>。
2. 改 templates/ 下的文件时，判断标准是「对一个陌生项目是否成立」，不是「对 context-dev 是否方便」。 那里的每一行都会成为别人项目的起点。
3. 完整版和 lite 两份 AGENTS.md.tmpl 的 .tmpl 后缀都不能去掉。 宿主会递归发现并全量注入仓库里所有 AGENTS.md，改回 .md 就等于把满是初始化占位符、开头写着「这个仓库还没初始化」的模板塞进本仓库每一轮对话。tests/ 里有用例锁着这条。
4. 根目录不补 docs/、scripts/、.agents/evals/。 两套骨架只存在于各自的 templates/ 下。在根目录再放一套会出现两份同名文件，而它们语义完全不同——一份是产出物，一份是配置。
5. 改了任何 templates/ 或三份脚本，同一次改动里更新 tests/ 和 README.md（改 lite 还要同步 lite/README.md）。 README 里有目录结构树和「设计取舍」清单，它是唯一的对外说明；漂了就是对每一个使用者说谎，而这正是这个框架声称要消灭的东西。
6. 不确定就问，不要编。 宿主行为、用户意图、某条规则当初为什么这么定——没在仓库里读到依据就先查证或先问。这个仓库的产出是「给 agent 看的规则」，一句猜出来的规则会被复制进每一个用户项目。
7. 改完自己跑与改动相关的验证命令。 动了脚本就 node --test，动了文档就把改到的链接点一遍。没跑就说"应该没问题"不可接受。
8. 破坏性操作先确认。 git push、强制推送、删分支、重置历史、递归删除——用户明确要求前一律不做。
9. 密钥和真实数据永不进仓库。 需要示例时用明显虚构的值。

术语

文档地图

可用技能

这五个是完整版产品，不是本仓库的开发工具；lite/skills/ 下的 init / maintain 是轻量版产品，与完整版二选一安装。在本仓库里它们只有一种正当用法：作为被修改的对象。

当前状态

v0.3.0（CONTEXT_DEV_VERSION 在完整版 scaffold.mjs、templates/scripts/audit-context.mjs 与 lite/scaffold.mjs 各有一份，改版本号要三处一起改）。完整版五个技能、lite 版两个技能齐全。完整版 DSH 正式支持、Codex 只验证安装与 frontmatter；lite 复用同一套 SKILL.md 触发机制，尚未单独做宿主端到端验证。

本仓库没有 docs/roadmap.md，范围没有文件级的唯一来源——新增能力前先在对话里把范围对齐，别默认「顺手加上更好」。

维护这份手册

• 改了命令、目录结构、铁律、术语 → 同一个改动里更新本文件。
• 细节增长超过 5 行 → 移到 README 或对应的 SKILL.md，这里只留链接。
• 本文件是占位符宿主，正文里别字面写出初始化占位标记，否则体检会把它当成没填完的空。
• 目标 150 行以内。本仓库根目录没有体检脚本，这条只能靠自觉。