| 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 |
两条铁律：
- 代码与文档同一次提交一起改——分开提交必然漂移。
- 每类信息只写一处，其余用链接（SSOT）——重复 = 迟早不一致。
不确定要不要更新某文档 → 先问用户。
新建文档前（防膨胀）
- 先按规范度三分定性（FIXED/SEMI/FLEXIBLE，见
profiles.md）：要建的若属结构层/主题层——先查是否已有同职责文档，有就并入/改名到标准名，不新建第二份；只有细节层才可自由新建（但必须挂链接）。
- 档位决定文档数量：别在 S 档建 M/L 才需要的
project-status / decision-log / specs；按 profiles.md 当前档位的文件集来，多出来的就是过度设计。
- 默认不为每个模块 / 每个功能建独立文档；模块文档是按需增量补，且新建后必须立刻从入口或
docs/README.md 链接到（否则就是孤立 = 失忆）。
- 临时报告（
*-report / *-check / *-analysis）不进主文档区，归档到 docs/archive/；任务层 specs/<feature>.md 完工后归档到 docs/specs/archive/。
核心原则
- 入口即记忆根：
CLAUDE.md / AGENTS.md 是唯一入口，承载三件套。
- 按稳定性梯度分层：稳定的"为什么/约定"（契约）与易变的"现在做到哪"（状态）分开放；决策只增不改（append-only），状态覆盖式保持当前真相。
- 规模 = 注入策略：S 全量读；L 转作用域 + 按需读（全量复述有真实 token 成本）。档位见
references/profiles.md。
- 文档是记忆不是复述：记决策、现状、坑、待办；不重复代码已说清的东西。
- SSOT：每类信息只有一个权威来源，其他用链接引用。
- 少而精：文档集由档位决定，按需增量，不强求铺满。
- 可链接才有效：孤立文档对 AI 不可见；判断孤立用 Grep 查链接即可，不需要复杂可达性图。
- 保守：不臆造（查不到就留空，别编）、幂等（重复运行收敛不重复）、不自动提交、语言跟随现有文档（中文项目写中文）。
最小文档集（由档位决定）
文档集大小由规模档位决定，完整清单见 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（接入记忆链）
- 定档位：读
references/profiles.md，按探测信号（模块数 / 是否 Monorepo / 协作规模 / 现有 .md 数）推断 S/M/L，报出推断 + 理由，让用户确认；宁可低估。
- 选主入口（用户拍板，忽略另一个）：
CLAUDE.md 对应 Claude runtime、AGENTS.md 对应 Codex runtime——是两个 runtime 各自的根文件，非主副关系。询问用户选哪个为主入口（默认 = 当前 runtime 对应的那个）。选定后只维护主入口；另一个直接忽略——不注入、不放指针、不碰它。注意：治理/规则文件位置也跟随选定 runtime（Claude 用 .claude/rules/，Codex 用其约定位置）。
- 读
references/templates.md 取注入块与该档位的模板。
- 幂等注入：先 Grep 锚点
<!-- dev-doc-structure:begin -->；存在 → 原地替换块内内容；不存在 → 追加。若入口已有同义规则，合并进去并告知用户，不新增重复段。
- 补建该档位文档集 + 可选规则补全：按
profiles.md 当前档位的清单补缺文档，不越档造页，新建即挂到入口/索引；规则文件若为空骨架，可接着走 seed-rules 从种子库补全通用 git/提交基线（见下）。
- 写前确认，不自动提交。
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 步的可选子步。
- 定档位 + 定规则位置：按
profiles.md「规则放哪」确定目标（S→入口 ## 开发约定 段；M/L→.claude/rules/project-rule.md）。
- 读种子库：
references/templates.md §5 通用规则种子库。
- 幂等比对：Grep 目标位置已有规则关键词（
提交/commit/<type>/密钥/token/测试），列出"已有 / 缺失"类别，只补缺失；已有但写法不同的报给用户，不覆盖。
- 核心直接种、可选逐条问：5a Git/提交（核心）可直接补；5b 提交时机、5c 其他（可选，且 5b 与"仅按需提交"默认冲突）→ 逐条征求用户是否启用。
- 占位不臆造：type 列表 / 测试命令 / 忽略路径等项目特定值留
[占位]，让用户填。
- git/提交/安全属常驻硬规则，不加
paths；写前确认，不自动提交。
安全与边界
- Pre-flight：写操作前先
git status 提醒；工作区有无关改动时不自动提交，提示用户先处理。
- 不自动提交，完成后汇报删改清单，由用户 review。
- 改动限定在请求范围，不顺手重排无关文档。
- 不适用：纯代码重构 / 单点 bug 修复 / 与文档结构无关的问答——直接做，别套这个流程。
