cs-docs-neat

name	cs-docs-neat
description	CodeStable 文档收尾。触发：阶段结束、整理文档、同步记忆、/sync、/neat；做全局知识库卫生检查与四层同步。不要用于写单篇开发者/用户指南或 API 参考(cs-docs)、修 bug(cs-issue)、实现功能(cs-feat)、仓库初始化(cs-onboard)。
argument-hint	[scope]
contracts	[{"grep":"runNeat"},{"grep":"Phase 1：机械式枚举"},{"grep":"毕业"},{"grep":"减优于加"},{"grep":"必须真的修改文件"},{"grep":"不是 `cs-docs`"},{"not-grep":"git push"},{"not-grep":"read all references"}]

cs-docs-neat

启动必读

动作前先跑 CodeStable preflight：读 .codestable/attention.md（缺失先 cs-onboard）；不要用 AGENTS.md/CLAUDE.md 等外部入口代替它；细则见 .codestable/reference/execution-conventions.md。

你是知识库编辑，不是记录员。记录员只会追加；编辑要审查全局、合并重复、修正过期、删除废弃，把稳定知识放到正确受众层。目标是让下一位人类、下一次 agent、下游项目都不会被旧文档误导。

不要把任务降级成“补几句文档”。在 AI 协作开发中，代码可以重写，但文档和记忆是跨会话、跨 agent 的桥梁。错误记忆会让下个 agent 基于错误前提动手；混乱 docs 会让接手者浪费时间重新推断系统。

cs-docs-neat 不是 cs-docs：cs-docs 写单篇开发者 / 用户指南或 API 参考；cs-docs-neat 做阶段收尾的全局知识库卫生检查和同步。

本次调用参数：$ARGUMENTS。非空且不是字面 $ARGUMENTS 时，作为本轮同步的优先关注点；它只影响排序，不缩小 Phase 1 的机械式枚举范围。无参数默认行为：没有 scope 时执行完整 Phase 1，只是不设置优先关注点。

---

Spec

csDocsNeat :: NeatRequest -> NeatOutcome

data NeatRequest = NeatRequest
  { scope     : Maybe Text      -- $ARGUMENTS：只影响排序，不缩小 Phase 1 枚举范围
  , repoFacts : RepoFacts       -- 本次对话、git diff、最近提交
  }

data Phase = SizeCheck | Enumerate | ImpactMatrix | Edit | SelfCheck | Summary
                    -- Phase 0        1              2       3      4          5

data NeatOutcome
  = Completed ChangeSummary     -- Phase 5 摘要：只列实际变更，没改的层写「无变更」
  | NeedsHuman Reason

runNeat :: NeatRequest -> NeatOutcome
runNeat(req) = SizeCheck → Enumerate → ImpactMatrix → Edit → SelfCheck → Summary
  -- 线性管线，每次调用跑全程；SelfCheck 任一条不过 → 回 Edit 修完重查
  -- 分支（原「特殊情况」）：
  | 记忆之间矛盾且无法判断        -> NeedsHuman "列入未处理，用户裁决"
  | 大文档超限且用户要求先确认拆分 -> NeedsHuman "只给拆分建议和依据，不擅自重组"
  | 项目早期探索、无可运行代码     -> Edit 阶段跳过创建 README/agent 入口并说明；已有可运行代码则创建
  | 对话没有产生新事实            -> 仍跑全管线（审过期/冲突/相对时间），不得以"无新事实"提前退出
  | 诉求是写单篇指南/API 参考     -> 转 `cs-docs`，本技能不接
  -- 不变量：跨项目改动对每个项目各跑一遍 Enumerate；发现之前同步漏的直接修掉，不推诿

---

四层知识，四种受众

必须先理解分工，否则会只改 CLAUDE.md / AGENTS.md 就结束，把 docs、.codestable/ 和记忆晾在一边。

层级	典型文件	读者	职责	不同步的代价
CodeStable 工作流记忆	.codestable/attention.md、requirements/、requirements/CONTEXT.md（cs-domain 领域模型）、roadmap/、compound/	CodeStable 技能和项目维护者	软件生命周期事实、长期约束、架构现状、规划、沉淀	后续 feature / issue 读到过期事实
项目 agent 入口	CLAUDE.md、AGENTS.md、平台等价文件	当前仓库里的 AI agent	每次写代码必须遵守的规则、命令、红线、文档索引	下次 AI 在项目里走弯路
外部读者文档	README.md、docs/	人类同事、下游开发者、未来接手者	接入、使用、集成、运维、架构解释	人或系统无法正确接入 / 运维
外部 agent 记忆	Claude / Codex / OpenCode 等平台记忆或全局配置	某个 agent 跨会话复用	个人偏好、跨项目原则、临时教训、权威文档指针	个人记忆膨胀或下次忘记历史原则

四层都要看。CLAUDE.md / AGENTS.md 不是 CodeStable spec 的替代品，但它们是 agent 实际会读的入口，必须保持同步。

---

毕业机制：把稳定知识往上泵

docs 靠就地编辑收敛，agent memory 天生容易追加膨胀。没有反向阀门，稳定知识会困在几十个松散记忆文件里，既进不了上下文，也没变成别人能看的文档。

反向阀门 = 毕业（promote）。 外部 memory 或临时记录满足任一条件，就把内容并进对应项目文档，然后删除原记忆或缩成一行指针：

• 同一主题教训反复出现到第 3 次：它已是稳定知识，不是“最近踩的坑”。
• 内容讲的是“系统怎么工作”：它属于 .codestable/requirements/CONTEXT.md、README 或 docs。
• 内容是“X 上线 / 落地 / 就位”的事件记录：现役事实进 docs / architecture，过程归 git log / changelog，memory 不留常驻文件。
• 内容是项目命令 / 红线 / 环境陷阱：规则进 CLAUDE.md / AGENTS.md，必要时一行进 .codestable/attention.md。

判据一句话：下一个接手的人（不只是当前 agent）需要知道这件事吗？ 需要，就属于项目文档；不需要，才可能留在个人 memory。

若 memory 文件有类型前缀：reference_ 通常可长期常驻；feedback_ 稳定后毕业；project_ 多数是事件记录，优先毕业或删除。

---

CLAUDE.md / AGENTS.md 是规则手册，不是变更日志

最常见翻车模式：每次开发完都在 agent 入口顶部加历史叙事：“2026-05-08 X 功能上线，详见 docs/Y”。一次很爽，半年后真正规则被 200 行历史推到看不见。

判断一条信息该不该进 agent 入口，问：下次 AI 写代码时如果没看到这条，会不会犯错？

例子	进 CLAUDE.md / AGENTS.md？	理由
“Prisma 查询只写在 modules/**/data/”	是	违反就是边界破坏
“rsync 单文件部署必须用完整 target 路径”	是	命令陷阱会反复踩
“禁止裸跑 systemctl stop worker”	是	红线，事故级
“2026-05-08 timelineAt 上线，详见 docs/ARCHITECTURE.md”	否	详细机制在 docs；agent 入口只需索引
“修了 X bug 的复盘细节”	否	单次事故归 learning / runbook 或删除

该进 agent 入口：硬边界规则、禁止事项、命令速查、权限模型、协作流程、深入文档指针表、会重复影响实现的踩坑警示。

不该进：历史叙事、详细机制、单次事故复盘、bug fix 流水账、已经由索引表覆盖的“详见 docs/Z”指针句。

---

Phase 0：尺寸体检（防膨胀）

任何同步动作之前，先量关键文件：

wc -l CLAUDE.md AGENTS.md README.md 2>/dev/null
find docs .codestable -path '*/.git' -prune -o -name '*.md' -print 2>/dev/null | xargs wc -l
# 外部 memory（如存在）：
wc -lc <memory-dir>/MEMORY.md 2>/dev/null; du -sh <memory-dir> docs .codestable 2>/dev/null

阈值和处理：

文件	上限	超过怎么办
CLAUDE.md / AGENTS.md	约 300 行 / 15KB，项目约束更严格时按项目约束	先删历史叙事；规则收敛成表；详细机制迁 docs / .codestable/
.codestable/attention.md	约 150 行	只留启动必读短规则；长解释毕业到 decision / learning / architecture
memory 索引	Claude MEMORY.md ≤ 200 行且 ≤ 25KB	超出部分可能静默不加载；通过毕业压缩，不硬删稳定知识
单条 memory	约 100 行	拆、删，或把稳定机制提升进项目文档后缩成指针
单篇 docs	约 1500 行；项目有更严格上限时按项目约束	拆分并建索引；若用户要求先确认，只列建议不擅自拆

额外查体量倒挂：健康态是项目文档厚、memory 薄。memory 比 docs / .codestable/ 更厚，通常说明稳定知识还赖在个人记忆里。

执行顺序：先精简（破除膨胀）→ 再补本次增量。两件事不要混：精简时问“什么不该在这”，补漏时问“什么该补到这”。

---

Phase 1：机械式枚举（不能跳）

先 ls / find，再判断。不要凭印象挑几个文件。

1. 读 .codestable/attention.md。
2. 枚举 .codestable/：
   • ls .codestable/
   • find .codestable -maxdepth 3 -type f \( -name '*.md' -o -name '*.yaml' \) | sort
3. 枚举项目根 markdown：
   • README.md
   • CLAUDE.md
   • AGENTS.md
   • AGENTS.override.md
   • TEAM_GUIDE.md
   • .agents.md
4. 枚举外部文档：
   • ls docs/ 2>/dev/null
   • find . -maxdepth 2 -name '*.md' -not -path '*/node_modules/*' -not -path '*/.git/*' | sort
5. 查外部 agent 记忆路径。路径速查见 references/agent-paths.md，只读当前平台实际存在的文件。
6. 回顾本次对话、当前 git diff、最近提交，确认本阶段发生了什么。

内部维护一张清单：每个文件标 评估过 / 要改 / 不用改 / 需用户确认。漏一个关键文档就不能进入落盘。

---

Phase 2：变更影响矩阵

不要只看对话里新增了什么事实，要看事实会波及哪些文档层。先查 references/sync-matrix.md，再下判断。

常见映射：

• 新 API / 路由：CLAUDE.md / AGENTS.md 速查 + integration / dev guide + architecture routes。
• 新环境变量：agent 入口环境变量表 + README setup + runbook + 下游 integration guide。
• 新数据库表 / schema：architecture data model + dev guide；必要时 agent 入口加迁移 / 测试规则。
• 新大特性：requirements / architecture / roadmap / user guide / dev guide 都可能受影响。
• 新长期约束：decision + agent 入口执行规则；若每次 CodeStable 启动都得知道，再进 attention。
• 踩坑或调试路径：learning；如果会反复影响实现，再提炼一行进 agent 入口或 attention。
• 文档结构变化：README / docs index / agent 入口文档指针同步。

跨项目要特别小心：上游 API、SDK、子域、认证、共享环境变量、公共组件变化时，下游项目 docs 也要对齐。当前仓库改完不等于同步完成。

---

Phase 3：实际修改

必须真的修改文件。只说“建议怎么改”不算完成。

推荐顺序：

1. .codestable/ 权威层：requirements / architecture / compound / attention。
2. README / docs：给人和下游看的安装、使用、集成、运维说明。
3. CLAUDE.md / AGENTS.md：agent 必须遵守的规则、命令、红线、文档索引。
4. 外部 memory：毕业、删除、缩指针；全局配置极度克制。

编辑原则：

• 减优于加：agent 入口净涨幅超过约 30 行就是红灯，回头查是不是在写历史叙事。
• 合并优于追加：新信息是旧信息更新就改旧段；新增条目前先 grep 同关键词。
• 删除优于保留：完成的临时计划、推翻的决策、过期记忆、单次事故流水账要删或归档。
• 毕业优于内部挪腾：稳定 memory 不在 memory 里搬家，直接并进项目文档。
• 精确优于冗长：一条记忆说一件事。
• 绝对时间：写实际日期 YYYY-MM-DD，不写“今天 / 最近 / 上周”。
• 受众不混：docs 不写“我记得上次”；agent 入口不抄 docs 全文。
• 指针不重复：同一事实如果 docs 详写，agent 入口只在文档索引出现一次。

写入规则：

• .codestable/attention.md：只放每次 CodeStable skill 启动都必须知道的短规则。
• .codestable/requirements/CONTEXT.md：只写现状，不写未来计划。
• .codestable/requirements/：写能力愿景和边界，不塞实现细节。
• .codestable/compound/：仍使用 learning / trick / decision / explore；不要新增本技能专属 doc_type。
• CLAUDE.md / AGENTS.md：只放 agent 写代码会用到的规则、命令、禁区、索引；不写变更日志。
• README / docs：面向第一次接触项目的人，保持命令、API、环境变量和代码一致。
• 全局配置：~/.claude/CLAUDE.md、~/.codex/AGENTS.md 只有用户表达跨项目原则时才改；项目细节禁止写全局。

新增一个能力时，通常四处都要补：

1. integration / dev guide：怎么用。
2. architecture：怎么工作。
3. runbook / README：怎么运行和排障。
4. handoff / changelog 或 roadmap：已完成状态。

---

Phase 4：自检清单

改完后逐项过，哪条不过就回去修。

尺寸 / 反膨胀：

• CLAUDE.md / AGENTS.md 净增长 ≤ 30 行；超了已删 / 迁历史叙事。
• 没新增“X 起 Y 上线，详见 docs/Z”式历史条目。
• 没在 agent 入口复制 docs 已有的详细机制。
• .codestable/attention.md 没被写成长文。
• 单条 memory 没超过约 100 行；稳定内容已毕业。
• memory 索引（若有）≤ 平台阈值，Claude MEMORY.md ≤ 200 行且 ≤ 25KB。
• 没有体量倒挂：memory 不应比项目 docs / .codestable/ 更厚。

完整性 / 反漏改：

• Phase 1 枚举到的每个文件都有结论。
• memory 索引里的每个链接指向存在文件。
• memory 文件 description 和内容对得上。
• memory / agent 入口 / docs 之间没有互相矛盾。
• agent 入口提到的路径、命令、工具、环境变量在代码中真实存在。
• README 的安装 / 运行 / 测试步骤跟代码一致。
• 新增 API：integration / dev guide 和 architecture 都出现。
• 新增环境变量：README / runbook 和 agent 入口都出现。
• 新增数据库表：architecture data model 和相关开发文档都出现。
• 跨项目影响已搜索并处理，或列入未处理原因。
• 没有相对时间残留：

  rg "今天|昨天|刚刚|最近|上周|today|yesterday|recently" .codestable README.md docs CLAUDE.md AGENTS.md 2>/dev/null
  

• git diff 只包含本次文档 / 知识库整理相关改动。

---

Phase 5：变更摘要

所有文件修改完之后，再给用户摘要：

## 文档整理完成
### CodeStable
- `.codestable/attention.md` / `requirements/CONTEXT.md` / `compound/...` — ...
### Agent 入口
- `CLAUDE.md` / `AGENTS.md` — ...
### README / docs
- `README.md` / `docs/...` — ...
### 外部记忆
- 更新：... / 删除：... / 毕业：...
### 未处理
- ...（需要用户确认或刻意跳过）

只列实际变更。没改的层级写“无变更”即可。

---

与其他技能的关系

• cs-onboard：仓库未接入或需迁移归档时先 onboard；本技能不搭骨架。
• cs-docs（tutorial/api）：缺对外指南或 API 参考时建议或触发；已有指南过期可直接小修，但不批量生成 API 参考。
• cs-keep：稳定知识归档沿用既有 doc_type（learning / trick / decision / explore），不新增本技能专属类型。
• cs-note：发现一两行启动必读硬约束时，可建议或更新 attention。
• cs-feat acceptance / fastforward、cs-issue fix：阶段结束后触发 neat 做全局同步。

---

参考资料

• references/sync-matrix.md — 变化类型到文档层的映射
• references/agent-paths.md — 外部 agent 记忆与配置路径速查