dev-doc-structure

name

dev-doc-structure

description

Use when setting up, auditing, or maintaining a project's developer documentation so it works as the AI's cross-session memory: tiers the doc set to project scale (S/M/L), routes where each doc and rule belongs, and aligns the structure (fill gaps, merge redundant docs, link orphans). Triggers: 文档结构 / 文档体系 / 知识库 / 文档导航 / 信息架构 / 文档分层 / 文档规模 / SSOT / 单一信息源 / 孤立文档 / 重复文档 / 冗余文档 / 文档臃肿 / 过期文档 / 文档即记忆 / 文档没人维护 / 规则放哪 / 加规则到哪 / 规则文件组织 / 规则补全 / 补全规则 / 通用 git 规则 / 提交规范 / seed rules / commit rules / 接着上次继续 / onboard docs into CLAUDE.md / where to put rules / documentation reading chain / cross-session memory. Also when a doc is missing, duplicated, orphaned (not linked from any entry), or has drifted from the code.

文档即记忆（dev-doc-structure）

定位

文档是 AI 的跨对话记忆层。每次对话的上下文都会丢失，文档是唯一能跨会话留存的记忆。

唯一记忆根是入口文件（Claude 用 CLAUDE.md，Codex 用 AGENTS.md）。它承载三件套：

• 文档地图：指向各文档的导航链接
• 阅读链：什么任务先读哪个文档（开工前读）
• 更新触发：改了什么就回写哪个文档（收尾前写）

一句话：开工前按阅读链读，收尾前按更新触发写。没被入口链接到的文档 = AI 看不见 = 等于失忆。

四种模式

模式	做什么	读哪个 reference
bootstrap（接入记忆链）	定档位 → 把"文档地图+阅读链+更新触发"注入入口 → 补建该档位的文档集	references/profiles.md + references/templates.md
update（回写记忆）	完成一段工作后，按更新触发把决策/现状/坑写回对应文档（按档位路由）	本文件表 B（无需额外读）
diagnose（体检）	识别档位 → 查孤立/重复/过期/三件套/可变性违规，只读不写	references/diagnose.md
seed-rules（规则补全）	定规则位置 → 从种子库幂等补全通用 git/提交/安全基线（只补缺失，核心直接种、可选问用户），让规则文件从空骨架变成可用基线	references/templates.md §5

与旧版任务的收敛映射（功能未缩水，只是归并）：诊断 / 可达性检查 / SSOT 检测 → diagnose；新建文档体系 / Rules 构建 / 入口注入 → bootstrap；单文档更新 / 局部合并 / 局部优化 → update。

不确定走哪个：用户说"整理 / 体检 / 有没有重复过期" → diagnose；说"建文档 / 接入 / 让 AI 记住" → bootstrap；说"把这次改动记下来 / 更新某文档" → update；说"补规则 / 加通用 git 规则 / 规则补全 / 提交规范" → seed-rules。

规模档位（S / M / L，叠加在四模式之上）

文档体系按项目规模分三档；同一套四模式，按档位决定"文档集多大、信息怎么分层、怎么注入"（seed-rules 按档位决定规则写到哪）。详见 references/profiles.md，下面是骨架。

层（按可变性）	S 微型	M 标准	L 大型 / Monorepo
契约（稳）	入口三件套	+ architecture.md	+ 跨子项目地图 + 协议文档
规则（行为/原则）	入口 ## 开发约定 段	.claude/rules/*.md（常驻）	.claude/rules/*.md + 局部规则带 paths
状态（覆盖,当前真相）	devlog.md 顶部"当前状态"块	project-status.md	每子项目一份
决策（append,不可变）	devlog.md 条目（决策+坑）	decision-log.md	每子项目 + 根级跨项目
任务（临时,完工归档）	无	可选	specs/<feature>.md

• 判档：bootstrap 先探测（模块数 / 是否 Monorepo / 协作规模 / 现有 .md 数）再向用户确认；宁可低估，从 S/M 起步，长大再升档。
• 升档只增不推翻：S 的 devlog 在 M 拆成 project-status（覆盖）+ decision-log（append）；M 在 L 复制进每个子项目 + 加任务层。
• 规范度三分（FIXED/SEMI/FLEXIBLE）：结构层（入口/规则/状态/决策/索引/CHANGELOG）名称数量锁死；主题层（architecture/api/config/…）一主题一份；细节层（specs/模块页/教程）自由，只要被链接可达。详见 profiles.md。
• 三条不变原则：① 按稳定性梯度分层（稳定的"为什么" vs 易变的"做到哪"分开）；② 三种可变性各有归宿（决策只增不改）；③ 规模 = 注入策略（大项目不全量读，转作用域+按需；规则用 .claude/rules/ 的 paths 作用域）。

何时读文档（阅读规则）

任务开始前，先读入口的文档地图，按下表跳到对应文档，再看代码。读"按需"那一份即可，不要全读。

表 A：任务信号 → 先读（右列按约定文件名锚定）

任务信号（关键词）	先读	没有就
接口 / API / 前后端通信 / 协议 / WebSocket	server-integration-guide.md（无则 docs/api.md + 前端 api-integration.md）	提示缺口，建议 bootstrap 补建
鉴权 / 权限 / 签名 / 安全	安全章节（多在 architecture.md 或安全专文）	现读现问
配置 / 环境变量 / 启动参数	docs/config.md（+ environment-setup.md）	—
数据结构 / 迁移 / SQL	docs/database.md	—
架构 / 模块边界 / 重构	docs/architecture.md（Monorepo 加 project-overview.md）	—
部署 / 发布 / 运维	docs/deployment.md	—
接着上次 / 之前怎么做的 / 继续 / 排查老问题	状态层：S 读 devlog.md 顶部"当前状态"块；M/L 读 project-status.md（现状/进行中/下一步/已知问题），追溯"为什么"再翻 decision-log.md	提示尚无状态/记忆文档，建议 bootstrap 建一份

何时更新文档（更新规则）

完成有意义的工作后，在同一次提交内回写。写"记忆"而不是"复述代码"。

表 B：变更类型 → 回写哪里 / 写什么

右列"回写哪里"按档位路由：S 一律写 devlog.md（状态进顶部块、决策/坑进条目）；M/L 按层分流到下表对应文件。

做了什么	回写哪里（S → M/L）	写什么（记忆视角）
新增 / 修订一条规则	S：入口 ## 开发约定 段；M：.claude/rules/project-rule.md；L：按类型入 .claude/rules/ 的 project-constitution(原则)/project-rule(行为)/doc-rule(文档)，局部规则加 paths: 作用域	规则本身（MUST/禁止，可检验）；别写进 CLAUDE.md 操作区（入口只导航+速查，不复述规则）
推进了进度 / 现状变了	devlog.md 当前状态块 → project-status.md	现状、进行中、下一步、已知问题（覆盖，保持是"当前真相"）
做了关键决策	devlog.md 条目 → decision-log.md（append，不就地改写）	背景 → 选了什么、为什么、放弃了什么 → 后果
解决了一个非显然的坑	devlog.md 条目 → decision-log.md	现象 → 根因 → 解决，防止下次重犯
开工一个较大功能（L）	— → 新建 specs/<feature>.md	立项书：目标/范围/任务清单；完工归档 specs/archive/，决策回流 decision-log.md
改了对外 API / 协议	api.md / server-integration-guide.md + 版本号	端点/字段/签名变更，破坏性要标注
改了数据库结构	database.md	表 / 字段 / 索引 / 迁移
改了配置项	config.md	新增或改动项、默认值、影响
调整了架构 / 模块边界	architecture.md	决策与权衡（不贴整段代码）
改了部署 / 发布流程	deployment.md	步骤、回滚、环境差异
发版	CHANGELOG.md	Added / Changed / Fixed / Removed

两条铁律：

1. 代码与文档同一次提交一起改——分开提交必然漂移。
2. 每类信息只写一处，其余用链接（SSOT）——重复 = 迟早不一致。

不确定要不要更新某文档 → 先问用户。

新建文档前（防膨胀）

1. 先按规范度三分定性（FIXED/SEMI/FLEXIBLE，见 profiles.md）：要建的若属结构层/主题层——先查是否已有同职责文档，有就并入/改名到标准名，不新建第二份；只有细节层才可自由新建（但必须挂链接）。
2. 档位决定文档数量：别在 S 档建 M/L 才需要的 project-status / decision-log / specs；按 profiles.md 当前档位的文件集来，多出来的就是过度设计。
3. 默认不为每个模块 / 每个功能建独立文档；模块文档是按需增量补，且新建后必须立刻从入口或 docs/README.md 链接到（否则就是孤立 = 失忆）。
4. 临时报告（*-report / *-check / *-analysis）不进主文档区，归档到 docs/archive/；任务层 specs/<feature>.md 完工后归档到 docs/specs/archive/。

核心原则

1. 入口即记忆根：CLAUDE.md / AGENTS.md 是唯一入口，承载三件套。
2. 按稳定性梯度分层：稳定的"为什么/约定"（契约）与易变的"现在做到哪"（状态）分开放；决策只增不改（append-only），状态覆盖式保持当前真相。
3. 规模 = 注入策略：S 全量读；L 转作用域 + 按需读（全量复述有真实 token 成本）。档位见 references/profiles.md。
4. 文档是记忆不是复述：记决策、现状、坑、待办；不重复代码已说清的东西。
5. SSOT：每类信息只有一个权威来源，其他用链接引用。
6. 少而精：文档集由档位决定，按需增量，不强求铺满。
7. 可链接才有效：孤立文档对 AI 不可见；判断孤立用 Grep 查链接即可，不需要复杂可达性图。
8. 保守：不臆造（查不到就留空，别编）、幂等（重复运行收敛不重复）、不自动提交、语言跟随现有文档（中文项目写中文）。

最小文档集（由档位决定）

文档集大小由规模档位决定，完整清单见 references/profiles.md。一句话概览：

• S 微型：入口 + docs/devlog.md（状态块 + 决策/坑条目合一）+ 可选 README.md。
• M 标准：入口 + docs/project-status.md（状态,覆盖）+ docs/decision-log.md（决策,append）+ 按需 architecture/api/config/database/deployment + docs/README.md。
• L 大型/Monorepo：每子项目一套 M 记忆集 + 任务层 docs/specs/<feature>.md + 根入口跨子项目地图 + 协议文档（如 server-integration-guide.md）。

"按需出现"自然覆盖 CLI / 库这类没有 API / 数据库的项目（缺的行不建）。

模式执行要点

bootstrap（接入记忆链）

1. 定档位：读 references/profiles.md，按探测信号（模块数 / 是否 Monorepo / 协作规模 / 现有 .md 数）推断 S/M/L，报出推断 + 理由，让用户确认；宁可低估。
2. 选主入口（用户拍板，忽略另一个）：CLAUDE.md 对应 Claude runtime、AGENTS.md 对应 Codex runtime——是两个 runtime 各自的根文件，非主副关系。询问用户选哪个为主入口（默认 = 当前 runtime 对应的那个）。选定后只维护主入口；另一个直接忽略——不注入、不放指针、不碰它。注意：治理/规则文件位置也跟随选定 runtime（Claude 用 .claude/rules/，Codex 用其约定位置）。
3. 读 references/templates.md 取注入块与该档位的模板。
4. 幂等注入：先 Grep 锚点 <!-- dev-doc-structure:begin -->；存在 → 原地替换块内内容；不存在 → 追加。若入口已有同义规则，合并进去并告知用户，不新增重复段。
5. 补建该档位文档集 + 可选规则补全：按 profiles.md 当前档位的清单补缺文档，不越档造页，新建即挂到入口/索引；规则文件若为空骨架，可接着走 seed-rules 从种子库补全通用 git/提交基线（见下）。
6. 写前确认，不自动提交。

update（回写记忆）

照表 B 找到目标文档（按档位路由：S→devlog；M/L→project-status / decision-log / specs）→ 追加"记忆视角"的内容 → 与代码同次提交。要点：状态层覆盖式保持当前真相；决策层 append-only 不就地改写；devlog/decision-log 时间倒序（最新在前）。模板见 references/templates.md。

diagnose（体检）

只读不写。读 references/diagnose.md：先识别当前档位，再走七项检查（孤立 / SSOT 重复 / 过期 / 入口三件套 / 档位匹配 / 可变性违规 / 结构对齐含规则基线缺失），产出精简报告与建议操作，再询问用户是否要执行（执行属于 bootstrap/update/seed-rules）。

seed-rules（规则补全）

目标：把通用 git / 提交 / 安全等基线规则幂等补全进规则位置，让规则文件从空骨架变成可用基线。可独立触发，也可作 bootstrap 第 5 步的可选子步。

1. 定档位 + 定规则位置：按 profiles.md「规则放哪」确定目标（S→入口 ## 开发约定 段；M/L→.claude/rules/project-rule.md）。
2. 读种子库：references/templates.md §5 通用规则种子库。
3. 幂等比对：Grep 目标位置已有规则关键词（提交/commit/<type>/密钥/token/测试），列出"已有 / 缺失"类别，只补缺失；已有但写法不同的报给用户，不覆盖。
4. 核心直接种、可选逐条问：5a Git/提交（核心）可直接补；5b 提交时机、5c 其他（可选，且 5b 与"仅按需提交"默认冲突）→ 逐条征求用户是否启用。
5. 占位不臆造：type 列表 / 测试命令 / 忽略路径等项目特定值留 [占位]，让用户填。
6. git/提交/安全属常驻硬规则，不加 paths；写前确认，不自动提交。

安全与边界

• Pre-flight：写操作前先 git status 提醒；工作区有无关改动时不自动提交，提示用户先处理。
• 不自动提交，完成后汇报删改清单，由用户 review。
• 改动限定在请求范围，不顺手重排无关文档。
• 不适用：纯代码重构 / 单点 bug 修复 / 与文档结构无关的问答——直接做，别套这个流程。