context-dev: Instructions file for Codex

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
语法检查	node --check .agents/skills/init/scaffold.mjs、node --check .agents/skills/init/templates/scripts/audit-context.mjs、node --check lite/scaffold.mjs
体检模板树（看输出用）	node .agents/skills/init/templates/scripts/audit-context.mjs
体检仓库根（CI 同款）	node .agents/skills/init/templates/scripts/audit-context.mjs --root .

语法检查里的三个文件、体检仓库根和 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 标记（初始化时被整份替换）