diff --git a/README.en.md b/README.en.md index f8fe9d3..d04c8c6 100644 --- a/README.en.md +++ b/README.en.md @@ -12,7 +12,7 @@ Tired of OpenSpec's flimsiness, Oh-My-OpenAgent's over-engineering, and Superpow

Status - CodeStable Skills + CodeStable Skills License

@@ -110,6 +110,8 @@ CodeStable models real coding work as **6 entities** and **3 flows**. | **Issue fixing** | `cs-issue-report` → `cs-issue-analyze` → `cs-issue-fix` | Tell AI what's wrong → AI finds the root cause → AI fixes precisely | | **Refactoring** | `cs-refactor` (beta) | Architectural rot doesn't happen overnight. AI assists, but **humans refactor**. Still iterating — feedback welcome | +At a phase or milestone boundary, use `cs-docs-neat` to reconcile `.codestable/`, README/docs, `CLAUDE.md` / `AGENTS.md`, and agent memory so docs do not drift from code. + --- ## Skill catalog diff --git a/README.md b/README.md index ad3eebc..ba0b4d3 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@

Status - CodeStable Skills + CodeStable Skills License

@@ -111,6 +111,8 @@ CodeStable 顺着软件编码的真实流程来设计，把开发活动建模成 | **问题修改** | `cs-issue-report` → `cs-issue-analyze` → `cs-issue-fix` | 跟 AI 说哪里有问题 → 让 AI 分析根因 → 让 AI 定点修复 | | **代码重构** | `cs-refactor` (beta) | 软件架构腐化不是一蹴而就的。AI 辅助重构，但**终归是人在重构**——还在迭代中，欢迎赐教 | +阶段或里程碑收尾时，用 `cs-docs-neat` 整理 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆，避免文档与代码脱节。 + --- diff --git a/SKILL_CATALOG.en.md b/SKILL_CATALOG.en.md index 7721955..a708756 100644 --- a/SKILL_CATALOG.en.md +++ b/SKILL_CATALOG.en.md @@ -32,3 +32,4 @@ | Explore and docs | `cs-audit` | Audit code for bug, security, performance, maintainability, and architecture risks | | Explore and docs | `cs-guide` | Write outward-facing developer guides | | Explore and docs | `cs-libdoc` | Generate reference docs for public library surfaces | +| Explore and docs | `cs-docs-neat` | Reconcile `.codestable/`, README/docs, `CLAUDE.md` / `AGENTS.md`, and agent memory at phase close | diff --git a/SKILL_CATALOG.md b/SKILL_CATALOG.md index 9081e6f..0458601 100644 --- a/SKILL_CATALOG.md +++ b/SKILL_CATALOG.md @@ -32,3 +32,4 @@ | 探索与文档 | `cs-audit` | 主动审计代码中的 bug 隐患、安全、性能、可维护性和架构偏离 | | 探索与文档 | `cs-guide` | 编写对外开发者指南 | | 探索与文档 | `cs-libdoc` | 为库的公开表面生成参考文档 | +| 探索与文档 | `cs-docs-neat` | 阶段收尾时同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆 | diff --git a/WORKFLOW.en.md b/WORKFLOW.en.md index 6955d46..68b81f2 100644 --- a/WORKFLOW.en.md +++ b/WORKFLOW.en.md @@ -14,10 +14,11 @@ cs ├── cs-feat-design -> cs-feat-design-review -> cs-feat-impl -> cs-feat-review -> cs-feat-qa -> cs-feat-accept ├── cs-issue-report -> cs-issue-analyze -> cs-issue-fix ├── cs-refactor / cs-refactor-ff - └── cs-learn / cs-trick / cs-decide / cs-explore / cs-note + └── cs-learn / cs-trick / cs-decide / cs-explore / cs-note / cs-docs-neat ``` Vertical means layers, not strict time order. Long-lived archives are refreshed repeatedly; the roadmap layer is entered for large needs. Execution is event-driven: new capability goes to feature flow, bugs go to issue flow, and code rot goes to refactor flow. The cross-cut layer is the knowledge flywheel. +`cs-docs-neat` is the phase-close cleanup skill: it reconciles `.codestable/`, README/docs, `CLAUDE.md` / `AGENTS.md`, and agent memory without adding a new archive document type. ## Runtime Structure diff --git a/WORKFLOW.md b/WORKFLOW.md index 1027124..00683b1 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -14,10 +14,11 @@ cs ├── cs-feat-design -> cs-feat-design-review -> cs-feat-impl -> cs-feat-review -> cs-feat-qa -> cs-feat-accept ├── cs-issue-report -> cs-issue-analyze -> cs-issue-fix ├── cs-refactor / cs-refactor-ff - └── cs-learn / cs-trick / cs-decide / cs-explore / cs-note + └── cs-learn / cs-trick / cs-decide / cs-explore / cs-note / cs-docs-neat ``` 纵向是层次，不是严格时间顺序。长效档案层会反复刷新，规划层只在大需求时进入。第 3 层是事件入口：新需求走 feature，bug 走 issue，腐化走 refactor。横切层是知识飞轮：任何流程都可以把值得复用的经验沉淀到 compound。 +`cs-docs-neat` 是阶段收尾整理器，负责同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆，不新增沉淀文档类型。 ## 运行时结构 diff --git a/cs-docs-neat/SKILL.md b/cs-docs-neat/SKILL.md new file mode 100644 index 0000000..3b6b244 --- /dev/null +++ b/cs-docs-neat/SKILL.md @@ -0,0 +1,283 @@ +--- +name: cs-docs-neat +description: CodeStable 文档与知识库收尾整理技能。用于阶段结束、里程碑完成、准备交接/提交、用户说"整理文档"、"同步记忆"、"更新 AGENTS/CLAUDE"、"收尾"、"这个阶段做完了"、"新人能直接上手"、"docs 过期/冲突了"、"sync up"、"tidy up docs"、"update memory"、"/sync"、"/neat"时，对 `.codestable/`、项目根 `CLAUDE.md` / `AGENTS.md`、README、docs/ 和可用 agent 记忆做全局盘点、反膨胀、补漏和冲突修正。 +--- + +# cs-docs-neat + +## 启动必读 + +开始任何判断或动作前，先读取 `.codestable/attention.md`；缺失则视为骨架不完整，提示先补齐或运行 `cs-onboard`，不要回退到外部 AI 入口文件。 + +你是**知识库编辑**，不是记录员。记录员只会追加；编辑要审查全局、合并重复、修正过期、删除废弃，把稳定知识放到正确受众层。目标是让下一位人类、下一次 agent、下游项目都不会被旧文档误导。 + +不要把任务降级成“补几句文档”。在 AI 协作开发中，代码可以重写，但文档和记忆是跨会话、跨 agent 的桥梁。错误记忆会让下个 agent 基于错误前提动手；混乱 docs 会让接手者浪费时间重新推断系统。 + +`cs-docs-neat` 不是 `cs-guide`：`cs-guide` 写单篇开发者 / 用户指南；`cs-docs-neat` 做阶段收尾的全局知识库卫生检查和同步。 + +--- + +## 四层知识，四种受众 + +必须先理解分工，否则会只改 `CLAUDE.md` / `AGENTS.md` 就结束，把 docs、`.codestable/` 和记忆晾在一边。 + +| 层级 | 典型文件 | 读者 | 职责 | 不同步的代价 | +|---|---|---|---|---| +| CodeStable 工作流记忆 | `.codestable/attention.md`、`requirements/`、`architecture/`、`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/architecture/`、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：尺寸体检（防膨胀） + +任何同步动作之前，先量关键文件： + +```bash +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（如存在）： + +```bash +wc -l /MEMORY.md 2>/dev/null +wc -c /MEMORY.md 2>/dev/null +du -sh 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/architecture/`：只写现状，不写未来计划。 +- `.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 和相关开发文档都出现。 +- [ ] 跨项目影响已搜索并处理，或列入未处理原因。 +- [ ] 没有相对时间残留： + ```bash + rg "今天|昨天|刚刚|最近|上周|today|yesterday|recently" .codestable README.md docs CLAUDE.md AGENTS.md 2>/dev/null + ``` +- [ ] `git diff` 只包含本次文档 / 知识库整理相关改动。 + +--- + +## Phase 5：变更摘要 + +所有文件修改完之后，再给用户摘要： + +```markdown +## 文档整理完成 + +### CodeStable +- `.codestable/attention.md` — ... +- `.codestable/architecture/...` — ... +- `.codestable/compound/...` — ... + +### Agent 入口 +- `CLAUDE.md` — ... +- `AGENTS.md` — ... + +### README / docs +- `README.md` — ... +- `docs/...` — ... + +### 外部记忆 +- 更新：... +- 删除：... +- 毕业：... + +### 未处理 +- ...（需要用户确认或刻意跳过） +``` + +只列实际变更。没改的层级写“无变更”即可。 + +--- + +## 特殊情况 + +- 项目还没有 README 或 `CLAUDE.md` / `AGENTS.md`：如果已有可运行代码就创建；还在早期探索就跳过并说明。 +- 对话没有产生新事实：仍要审查现有文档是否过期、冲突、含相对时间。 +- 记忆之间出现无法判断的矛盾：列到“未处理”让用户决定；这是少数需要用户介入的情况。 +- 跨项目改动：每个项目都跑一遍 Phase 1，不要假设上游文档改了下游就不用改。 +- 发现之前同步漏了东西：直接修掉，不要说“那不是这次对话的事”。 +- 用户明确要求先确认大文档拆分：只给拆分建议和依据，不擅自重组。 + +--- + +## 与其他技能的关系 + +| 技能 | 关系 | +|---|---| +| `cs-onboard` | 仓库未接入或需要迁移归档时先 onboard；本技能不负责搭骨架 | +| `cs-guide` | 发现缺对外指南时建议或触发；已有指南过期可直接小修 | +| `cs-libdoc` | 公开 API 参考缺失或过期时建议 libdoc；本技能不批量生成 API 参考 | +| `cs-learn` / `cs-trick` / `cs-decide` / `cs-explore` | 发现稳定知识要归档时使用这些既有 doc_type | +| `cs-note` | 发现一两行启动必读硬约束时，可建议或更新 attention | +| `cs-feat-accept` / `cs-issue-fix` / `cs-feat-ff` | 阶段结束后触发 neat 做全局同步 | + +--- + +## 参考资料 + +- `references/sync-matrix.md` — 变化类型到文档层的映射 +- `references/agent-paths.md` — 外部 agent 记忆与配置路径速查 diff --git a/cs-docs-neat/references/agent-paths.md b/cs-docs-neat/references/agent-paths.md new file mode 100644 index 0000000..fe30cf4 --- /dev/null +++ b/cs-docs-neat/references/agent-paths.md @@ -0,0 +1,58 @@ +# Agent 记忆与入口路径速查 + +执行 `cs-docs-neat` 时按当前实际存在的文件读取。没有独立 memory 的平台就跳过 memory 层，但仍要检查项目根 agent 入口。 + +## 项目根 agent 入口 + +| 文件 | 用途 | +|---|---| +| `CLAUDE.md` | Claude Code 项目级指令 | +| `AGENTS.md` | Codex 项目级指令 | +| `AGENTS.override.md` | Codex 同目录 override，存在时必须读 | +| `TEAM_GUIDE.md` / `.agents.md` | 部分团队或工具的 fallback 入口，存在时读 | + +这些文件需要同步，但只放 agent 执行需要的规则、命令、红线、文档索引；不要变成项目 changelog。 + +## Claude Code + +| 用途 | 路径 | +|---|---| +| 项目级指令 | 项目根 `CLAUDE.md` | +| 全局指令 | `~/.claude/CLAUDE.md` | +| 项目 memory | `~/.claude/projects//memory/` | +| memory 索引 | `~/.claude/projects/<...>/memory/MEMORY.md` | + +Claude memory 常用 frontmatter：`name`、`description`、`type`。稳定项目事实应毕业到项目文档，memory 留个人偏好或指针。 + +## OpenAI Codex + +| 用途 | 路径 | +|---|---| +| 项目级指令 | 项目根 `AGENTS.md` | +| 项目级 override | `AGENTS.override.md` | +| 全局指令 | `~/.codex/AGENTS.md` 或 `$CODEX_HOME/AGENTS.md` | + +Codex 通常没有独立的项目 memory 文件。项目事实不要写进全局 `AGENTS.md`；应写项目根 `AGENTS.md` 或 `.codestable/`。 + +## OpenCode + +| 用途 | 路径 | +|---|---| +| 全局配置 | `~/.config/opencode/` | +| 项目配置 | `.opencode/` | +| 项目 skills | `.opencode/skills/`、`.claude/skills/`、`.codex/skills/` | + +若 `.opencode/` 内有项目指令或 memory 类文件，按 agent 入口处理。 + +## OpenClaw + +| 用途 | 路径 | +|---|---| +| 用户级 skills | `~/.openclaw/skills/` | +| 项目级 skills | `.openclaw/skills/` | + +OpenClaw 没有统一 memory 约定；发现项目级指令文件时按 agent 入口检查。 + +## 全局配置边界 + +`~/.claude/CLAUDE.md`、`~/.codex/AGENTS.md` 等全局配置只有在用户表达了跨项目原则时才改。项目专属事实禁止写全局；把它们迁回项目根或 `.codestable/`。 diff --git a/cs-docs-neat/references/sync-matrix.md b/cs-docs-neat/references/sync-matrix.md new file mode 100644 index 0000000..7aa407e --- /dev/null +++ b/cs-docs-neat/references/sync-matrix.md @@ -0,0 +1,52 @@ +# 文档同步影响矩阵 + +遇到不确定"这次变化要同步哪些文档"时查本表。两个方向都要看：补漏（该加到哪里）和反膨胀（该从哪里删）。 + +## 先删 / 迁的反模式 + +| 反模式 | 处理 | +|---|---| +| `CLAUDE.md` / `AGENTS.md` 顶部堆"某日某功能上线" | 删除；历史归 git log / changelog，稳定事实归 docs 或 `.codestable/` | +| agent 入口里复制 architecture / design 的详细机制 | 删除细节，只留规则和文档索引 | +| `.codestable/attention.md` 写成长篇事故复盘 | 提炼成一行硬约束；细节归 learning / runbook | +| 外部 memory 描述项目架构 / API / 工作流 | 毕业到 `.codestable/architecture/`、README 或 docs；memory 留指针或删除 | +| 单次调试流水账长期保留 | 留可复用坑点到 learning；其余删除 | +| 已被新版本取代的中间态说明 | 保留最终态；旧文档标 superseded 或删除临时记忆 | +| README 和 docs 命令互相矛盾 | 以代码和实际可运行命令为准统一 | + +判断句：下次 agent 写代码时不看这条会犯错吗？会，进 agent 入口或 attention；不会，进 docs / compound / git log，或者删。 + +## 代码或行为变化 → 文档层 + +| 变化 | `.codestable/` | `CLAUDE.md` / `AGENTS.md` | README / docs | +|---|---|---|---| +| 新增 API / 路由 | architecture routes；必要时 requirement | 路由速查或测试命令，只写 agent 会用到的 | integration / dev guide，示例和错误码 | +| 新增环境变量 | architecture / decision（如是长期约束） | 本地运行必需变量和禁区 | README setup、operator runbook | +| 新增数据库表 / schema | architecture data model | 迁移/测试注意事项 | dev guide / architecture docs | +| 新功能 / 用户流程 | requirement 当前能力；architecture 现状；roadmap 状态 | 相关命令或目录规则 | user guide / README usage | +| 新长期约束 / 技术选型 | decision；attention 候选 | 必须遵守的规则 | 架构说明或开发者指南 | +| 踩坑 / 调试路径 | learning；必要时 attention 一行 | 会反复影响实现的红线 | runbook troubleshooting | +| 公开 API / CLI / 组件表面变化 | architecture 索引或 libdoc 关联 | 测试/发布注意事项 | libdoc / dev guide | +| 文档结构调整 | reference / system overview 如涉及 CodeStable | 文档索引更新 | README / docs index | + +## 外部 memory 毕业规则 + +| memory 内容 | 处理 | +|---|---| +| 个人偏好、跨项目协作原则 | 可留在外部全局记忆 | +| 项目专属命令 / 红线 | 迁到 `CLAUDE.md` / `AGENTS.md`，必要时同步 `.codestable/attention.md` | +| 项目架构 / API / 业务能力 | 迁到 `.codestable/architecture/`、requirements 或 docs | +| 稳定踩坑 | 迁到 `.codestable/compound/` 的 learning | +| 长期规定 | 迁到 decision，并在 agent 入口保留一行执行规则 | +| 事件流水账 | 删除；必要时由 git log / changelog 承担 | + +## 跨项目影响 + +以下情况必须搜索下游项目或相关 docs： + +- 上游 API / SDK / 协议变更。 +- 共享域名、子域、环境变量、认证方式变化。 +- 公共组件或基础设施升级。 +- 文档里有"如何接入本项目"的说明。 + +当前仓库改完不代表同步完成；依赖方的 setup / integration 文档也可能要改。 diff --git a/cs-feat-accept/SKILL.md b/cs-feat-accept/SKILL.md index 3297923..ac6f064 100644 --- a/cs-feat-accept/SKILL.md +++ b/cs-feat-accept/SKILL.md @@ -298,7 +298,8 @@ final audit 发现任何缺口： 3. 接口变更 / 用户可见行为变更 → "需要更新指南吗？（`cs-guide`）" 4. 库公开接口（组件 / 函数 / 命令）变了 → "需要更新 API 参考吗？（`cs-libdoc`）" 5. 第 8 节有 attention.md 候选 → 逐条问"候选 X 加到 attention.md 吗？" 用户明确同意 → 触发 `cs-note` 走分节归类 / 查重 / 软上限检查（不在 accept 里手写，避免和 cs-note 各搞一套口径）；**一次一条** -6. 最后问是否代为 scoped-commit +6. 阶段 / 里程碑收尾、准备交接，或本次改动影响 README/docs、`CLAUDE.md` / `AGENTS.md`、agent 记忆 → "要做一轮文档与记忆整理吗？（`cs-docs-neat`）" +7. 最后问是否代为 scoped-commit 收尾提交规则看 `shared-conventions.md` 第 4 节。提交范围：功能代码 + 方案 doc + 验收报告 + 本次实际更新的架构 doc / req doc / roadmap items.yaml + 主文档。 diff --git a/cs-feat-ff/SKILL.md b/cs-feat-ff/SKILL.md index 2ecf5a4..64362d2 100644 --- a/cs-feat-ff/SKILL.md +++ b/cs-feat-ff/SKILL.md @@ -184,7 +184,8 @@ tags: [...] 1. 暴露的坑 → "沉淀 learning？（`cs-learn`）" 2. 拍板的长期约束 → "归档决定？（`cs-decide`）" -3. 最后问是否代为 scoped-commit +3. 快速改动影响 README/docs、`CLAUDE.md` / `AGENTS.md` 或 agent 记忆 → "做一轮文档与记忆整理吗？（`cs-docs-neat`）" +4. 最后问是否代为 scoped-commit --- diff --git a/cs-issue-fix/SKILL.md b/cs-issue-fix/SKILL.md index 7451f95..e88688d 100644 --- a/cs-issue-fix/SKILL.md +++ b/cs-issue-fix/SKILL.md @@ -128,7 +128,8 @@ issue-fix 比 feature-implement 更谨慎：**触发反射信号但结论是"该 1. 暴露了值得复用的坑点 → "沉淀 learning？（`cs-learn`）" 2. 沉淀出长期约束 / 规约 / 技术决定 → "归档决定？（`cs-decide`）" 3. 这个 bug 暴露了项目通用的硬约束 / 命令陷阱 / 环境设置（一两行能讲清、CodeStable 技能每次启动都该知道）→ "记到 attention.md？（`cs-note`）" -4. 最后问是否代为提交。同意时按收尾提交规则执行 +4. 修复暴露了 README/docs、`CLAUDE.md` / `AGENTS.md` 或 agent 记忆不一致 → "做一轮文档与记忆整理吗？（`cs-docs-neat`）" +5. 最后问是否代为提交。同意时按收尾提交规则执行 建议：把 issue 目录文件和代码改动放同一次提交方便追溯；"顺手发现"另开 `cs-issue-report` 处理别塞这个 PR。 diff --git a/cs-onboard/reference/shared-conventions.md b/cs-onboard/reference/shared-conventions.md index 5228851..4de831d 100644 --- a/cs-onboard/reference/shared-conventions.md +++ b/cs-onboard/reference/shared-conventions.md @@ -179,19 +179,27 @@ planned → dropped （cs-roadmap update 模式，用户决定不做时改 2. `cs-decide`：长期约束 / 选型 3. `cs-guide`：开发者 / 用户指南 4. `cs-libdoc`：公开 API 参考 -5. `scoped-commit` +5. `cs-docs-neat`：阶段 / 里程碑收尾时同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆 +6. `scoped-commit` **issue-fix** 收尾按顺序判断： 1. `cs-learn`：坑点 2. `cs-decide`：暴露的长期约束 -3. `scoped-commit` +3. `cs-docs-neat`：修复暴露了文档、agent 入口或记忆不一致时做全局整理 +4. `scoped-commit` **feature-ff** 收尾按顺序判断（比标准 acceptance 短，没有 architecture / req 回写动作）： 1. `cs-learn`：动手过程暴露的坑 2. `cs-decide`：动手过程拍板的长期约束 -3. `scoped-commit` +3. `cs-docs-neat`：快速改动影响 README/docs 或 agent 入口时同步 +4. `scoped-commit` + +**roadmap** 收尾按顺序判断： + +1. `cs-docs-neat`：roadmap 确认落盘或整个 roadmap goal 完成后，同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆 +2. 后续若要自动推进整份 roadmap，再走 `cs-roadmap-impl-goal` **统一规则**：一律一句话提示；用户说"不用"立即跳过；不强制；上游主动提示，下游承接执行。 diff --git a/cs-onboard/reference/system-overview.md b/cs-onboard/reference/system-overview.md index c431425..9281dee 100644 --- a/cs-onboard/reference/system-overview.md +++ b/cs-onboard/reference/system-overview.md @@ -44,6 +44,7 @@ CodeStable 把这几类场景各配一套子技能，产物放进统一的目录 - `cs-feat-design-review` — feature design 人工确认前的只读方案审查 gate - `cs-guide` — 写给外部读者的开发者指南 / 用户指南 - `cs-libdoc` — 为库的公开 API 逐条目生成参考文档 +- `cs-docs-neat` — 阶段 / 里程碑收尾时，全局整理 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆，做反膨胀、补漏和冲突修正 ## 场景路由 @@ -68,6 +69,7 @@ CodeStable 把这几类场景各配一套子技能，产物放进统一的目录 | 可复用的编程模式、库用法 | `cs-trick` | | 开发者指南 / 用户指南 | `cs-guide` | | 库 API 参考 | `cs-libdoc` | +| 阶段收尾 / 整理文档 / 同步 agent 入口 / 新人交接 | `cs-docs-neat` | 完整的操作手册、退出条件、和其他工作流的关系,各子技能里讲。 @@ -83,6 +85,8 @@ learning / trick / decision / explore 都是存档文档类型,区别在记录 四者共用 `.codestable/compound/` 目录,靠 frontmatter 的 `doc_type` 字段和文件名中间的类型段(`YYYY-MM-DD-{doc_type}-{slug}.md`)区分。每个子技能只认自己的 `doc_type`,不读写别家产物——**"A 和 B 有什么不同"这种判断由本节负责,子技能里不再重复**。 +`cs-docs-neat` 不新增沉淀文档类型。它是收尾整理器：发现该沉淀的知识时，仍然使用 learning / trick / decision / explore 这些既有 doc_type；同时同步 README/docs、`CLAUDE.md` / `AGENTS.md` 和外部 agent 记忆。 + ## 愿景档案 vs 结构档案 vs 规划档案 vs 单次动作 diff --git a/cs-roadmap-impl-goal/SKILL.md b/cs-roadmap-impl-goal/SKILL.md index 206ff6f..53a3301 100644 --- a/cs-roadmap-impl-goal/SKILL.md +++ b/cs-roadmap-impl-goal/SKILL.md @@ -202,6 +202,7 @@ features: - architecture / requirement / roadmap 回写完成 - 最终审计通过 - 已做 learning reflection：筛出 pitfall / knowledge 候选，并建议用户确认后再运行 `cs-learn` +- 已提示用户可运行 `cs-docs-neat`，同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆 - transcript 打印 `CS_ROADMAP_GOAL_COMPLETE` 注意：goal 会话只自动做学习点反思和候选筛选，不自动写 `.codestable/compound/`。长期知识库归档必须由用户确认后触发 `cs-learn`，按它自己的查重、提炼、review、归档流程执行。 diff --git a/cs-roadmap-impl-goal/references/protocol.md b/cs-roadmap-impl-goal/references/protocol.md index 3babdd3..29930d5 100644 --- a/cs-roadmap-impl-goal/references/protocol.md +++ b/cs-roadmap-impl-goal/references/protocol.md @@ -362,7 +362,7 @@ CS_ROADMAP_GOAL_COMPLETE Roadmap complete. Features accepted: <数量> Final audit passed. -Manual follow-up: <事项|none> +Manual follow-up: ``` 只有 `CS_ROADMAP_GOAL_COMPLETE` 出现，`/goal` 才算满足。 diff --git a/cs-roadmap/SKILL.md b/cs-roadmap/SKILL.md index f513138..ee7ee17 100644 --- a/cs-roadmap/SKILL.md +++ b/cs-roadmap/SKILL.md @@ -167,6 +167,8 @@ description: 把"大到塞不进单个 feature"的需求做成完整事前规划 如果用户想把整份 roadmap 自动推进到底，确认落盘后提示下一步可以走 `cs-roadmap-impl-goal`：它会先完成所有子 feature design + design review，再让用户二次确认，最后输出可直接运行的 goal 指令。 +确认落盘后再提示一句："这份 roadmap 已经改变了后续工作入口和文档索引，要不要做一轮文档与记忆整理？（`cs-docs-neat`）" 用户说不用就跳过；这是收尾引导，不是 roadmap 通过条件。 + --- ## 和 feature 流程的衔接 diff --git a/cs/SKILL.md b/cs/SKILL.md index 07de6e9..fedd82e 100644 --- a/cs/SKILL.md +++ b/cs/SKILL.md @@ -88,6 +88,7 @@ CodeStable 把开发活动建模成 **7 个实体 + 3 个流程**，所有产物 | 一两行的项目注意事项 / 编译特殊设置 / 命令陷阱 / "记到 attention.md" | `cs-note` | | 开发者指南 / 用户指南 | `cs-guide` | | 库 API 参考 | `cs-libdoc` | +| 阶段收尾 / 整理文档 / 同步 `CLAUDE.md` 或 `AGENTS.md` / 新人交接 | `cs-docs-neat` | | 用户在 feature / issue 流程中间问"下一步" | 路由到对应入口（`cs-feat` / `cs-issue`），让该入口判断当前阶段 | **判不出来 / 太抽象**："听起来像 {猜测}，但你描述里 {缺什么}。是 {选项 A} 还是 {选项 B}？" 让用户选不要硬猜。 @@ -124,6 +125,7 @@ CodeStable 把开发活动建模成 **7 个实体 + 3 个流程**，所有产物 - 规定"全项目今后都按 X 来" → `cs-decide` - 调查"X 现在是什么样" → `cs-explore` - 一两行常驻提示"CodeStable 技能每次启动都得知道 X" → `cs-note`（写到 `.codestable/attention.md`） +- 阶段收尾后全局检查 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md`、agent 记忆是否同步 → `cs-docs-neat` 判不出问用户："这个你想记成 {踩坑回顾 / 复用处方 / 长期规约 / 调研存档 / 常驻提示} 哪一种？"