LetheChen 生成 CLAUDE.md / AGENTS.md + TODO.md
为项目生成项目专属的 AI 编码规则文件（CLAUDE.md / AGENTS.md）+ 活的 TODO.md 任务清单。
两个核心模式：
- HumanLayer 极简模式 — 根文件 ≤60 行，不写目录树 / 架构概览 / 不可验证的废话
- Karpathy 4 条准则 — Think Before Coding / Simplicity First / Surgical Changes / Goal-Driven Execution
关键机制：把 ## Session Maintenance Protocol 块嵌入到根文件顶部，未来的 agent 加载根文件时自动按决策表自检更新 TODO.md 和规则——软自动，零依赖（详见末尾「更新机制」）。
工作流
Step 0：平台与目标文件检测
按以下信号判定输出文件名（多个信号取并集）：
| 信号 | 偏好 |
|---|---|
| 存在 .claude/ 目录 | Claude Code（写 CLAUDE.md） |
| 存在 .codex/ 目录 | Codex（写 AGENTS.md） |
| 已 commit 的 CLAUDE.md | 保留，写 CLAUDE.md |
| 已 commit 的 AGENTS.md | 保留，写 AGENTS.md |
| 用户显式说 Codex / Claude Code / 两个都要 | 用户说了算 |
| 都检测不到 | 默认双写（最安全） |
不要在没有信号时强行猜。
Step 1：项目扫描
并行读取（Codex 用 shell_command，Claude Code 用 Read）：
- Manifest：package.json / pyproject.toml / go.mod / Cargo.toml / pom.xml → 语言、框架、scripts
- README：前 50 行 → 项目意图 + 主语言
- 现有规则文件：CLAUDE.md / AGENTS.md（合并策略见 Step 3）
- 现有 TODO.md（迁移但不覆盖）
- 代码风格：.eslintrc* / biome.json / .prettierrc*
- 任务运行器：Makefile / justfile / package.json scripts
- CI：.github/workflows/
- Monorepo 检测：顶层是否含 apps/ packages/ services/ modules/
- TODO 注释：扫一次 TODO / FIXME / HACK（为 TODO.md 提供初始项）
空项目（无代码）→ 停下来问用户，不要编造。
Step 2：决定文件布局
是否有清晰技术栈？ ├── 否 → 问用户，不要生成 └── 是 │ 是否 monorepo（apps/ packages/ services/ 多个子包）？ ├── 是 → Layout C └── 否 │ 源代码 < 10 且无 DB / 无 auth？ ├── 是 → Layout A（仅根文件） └── 否 → Layout B（根文件 + 规则目录，默认）
- Layout A — 仅根文件 CLAUDE.md / AGENTS.md
- Layout B — 根文件 + .claude/rules/*.md（默认）
- Layout C — Monorepo 根文件 + 每个子包一份规则
Step 3：合并策略（如目标文件已存在）
| 段 | 处理 |
|---|---|
| 缺失段 | 添加并填入检测结果 |
| 段内容是占位符（<...> / 空） | 填充 |
| 段内容是真实文本 | 保留，不覆盖 |
| Things to avoid 段 | 追加到末尾，不删现有条目 |
| Verification 命令 | 仅在原命令跑不通时更新；保留用户已写好的命令 |
| Workflow 分支/提交规范 | 保留用户约定，不擅自改成「标准」约定 |
| Session Maintenance Protocol 段 | 重新生成（skill 自身维护的，不属于用户手写） |
| Language 段 | 重新生成（4 字段必填） |
反例：不要因为「检测到 package manager 是 npm」就覆盖用户写的「我们用 pnpm」。
Step 4：生成根文件（CLAUDE.md / AGENTS.md）
按 \references/root-template.md 模板填充。要点：
- 顶部插入「会话维护协议」块（见 Step 7）—— 这是本 skill 的核心交付
- 60 行硬上限
- 4 个 Karpathy 准则压缩到 1-2 行
Language 4 字段必填
- 末尾给一条真实可跑的 verification 命令
- 不写目录树、不写架构概览
Step 5：生成 TODO.md
按 examples/TODO.md 骨架填 4 段：
- 🔴 进行中（≤3 项）
- 🟡 待处理（带 P1/P2 优先级 + 源链接）
- 🟢 后续（低优先级）
- ✅ 已完成（初始化时为空）
填充来源（来自 Step 1 扫描）：
- 注释里的 TODO / FIXME / HACK → 🟡
- 缺少测试的源文件 → 🟢
- 硬编码值 / 魔数 → 🟢
- 顶层目录里 README 提到的「待办」/「TODO」→ 🟡
- 没扫到 → 留空，不编造（这是核心原则）
Step 6：生成 .claude/rules/*.md（仅 Layout B / C）
按 \references/rule-file-template.md 模板。每个文件：
- paths: frontmatter 决定何时加载
- 30-80 行
- 单个关注点
- 最多 200 行
- 命名：lowercase-hyphen，api-conventions.md 而非 \rules.md
Step 7：会话维护协议（核心新机制）
每个生成的根文件顶部必须嵌入「会话维护协议」段（短版，写在根文件里），完整决策表在 \references/session-maintenance-protocol.md（长版，被规则文件引用）。
短版固定模板（中文版；英文版见 \references/session-maintenance-protocol.md 末尾）：
`markdown
Session Maintenance Protocol
开始时：读 TODO.md，复述当前 🔴 和 🟡 段，确认本次会话要推进哪几项。
结束前（最后一条用户消息之后、停止前必做）：
- 回看本次会话实际做了什么 —— 改动的文件、发现的问题、用户新增的约束
- 更新 TODO.md（决策表见 \references/session-maintenance-protocol.md）：
- 完成了某项 → 移到 ✅ 段，加 (YYYY-MM-DD)
- 新发现的问题 → 加到 🟡（P1/P2）或 🟢（P3+），附源链接
- 放弃某项 → 移到 ✅ 段，备注 已放弃：<原因>
- 更新本文件的规则 —— 如果本次会话暴露了新的项目级约定：
- 用户反复纠正的行为 → 加到 Things to avoid 段
- 反复跑错的命令 → 更新 Verification 段
- 隐含约定 → 加到 Project conventions 段
- 刷新日期戳 > 最后更新：YYYY-MM-DD（即使其他都没变）
触发条件（满足任一即必须更新 TODO.md）：≥1 个源文件被改 · 用户新增了约束 · 会话 > 10 分钟 `
Step 8：自检清单
声明完成前必跑：
- 根文件 ≤60 行（不含代码块）
- 根文件无目录树、无架构概览
- 根文件顶部带「会话维护协议」段
- TODO.md 4 段都有（即使空也留骨架）
- 所有 rule 文件有 paths: frontmatter
- 没有任何 rule 文件 >200 行
-
Language 4 字段全填
- Verification 命令真的能跑（用 bash -c 试一次）
- 没复制粘贴无用的框架默认
- 本仓库自己的 AGENTS.md / CLAUDE.md 也满足以上全部（self-dogfooding）
Step 9：给用户回执
` Created:
- AGENTS.md (XX 行) — 满足 60 行硬上限，带会话维护协议头
- CLAUDE.md (XX 行) — 同上
- TODO.md — 4 段骨架
- .claude/rules/api-conventions.md
- ...
Next:
- 打开每个文件，确认推断的规则和你的团队实际一致
- 手动跑一次 verification 命令，确认能跑通
- 提交。观察下一轮 AI 会话——任何被忽略的规则都要重写
- 根文件接近 200 行时，再次触发本 skill 拆分
- 第一次编码会话后回看本文件 —— 会话维护协议第 3 步会要求 agent 自己加新规则 `
参考资料
| 文件 | 用途 |
|---|---|
| \references/root-template.md | 根文件骨架（已带会话维护协议头） |
| \references/rule-file-template.md | 单个 rule 文件骨架 |
| \references/content-rules.md | 内容取舍规则（放什么、不放什么） |
| \references/rules-splitter.md | Layout A/B/C 决策树 + 检测矩阵 |
| \references/karpathy-rules.md | Karpathy 4 条准则原文 |
| \references/session-maintenance-protocol.md | 会话维护决策表（必读） |
| \references/install.md | 安装到 ~/.codex/skills/ / ~/.claude/skills/ 的步骤 |
| \references/quick-start.md | 5 分钟上手（生成 → 检查 → 提交 → 维护） |
| examples/TODO.md | 完整 TODO.md 范例 |
| examples/humanlayer-CLAUDE.md | HumanLayer 模式范例 |
| examples/karpathy-CLAUDE.md | 纯 Karpathy 模式范例 |
| examples/monorepo-root-CLAUDE.md | Monorepo workspace 根（Layout C） |
| examples/monorepo-package-AGENTS.md | Monorepo 子包（带 paths: frontmatter） |
| examples/api-conventions.md | 单个 rule 文件范例 |
更新机制
本 skill 不带 hook / cron / 外部触发器。## Session Maintenance Protocol 块嵌入在生成的根文件（CLAUDE.md / AGENTS.md）顶部，agent 每次新会话自动加载根文件，看到协议块就按决策表更新 TODO.md。
这是软自动：依赖 agent 自觉执行。优点是跨所有 agent、零依赖；代价是上下文太挤或任务急时可能跳过。决策表本身（\references/session-maintenance-protocol.md）是 single source of truth，根文件短版必须与之锁步。