文档结构

深模块：一个单元围绕清晰职责承载完整能力，将相关复杂细节收在内部。用于文档管理，就是让同一职责的资料集中在一个文件夹或文档中，读者能在这里找到解决该类问题所需的内容；“深”不指目录层级多或篇幅长。

浅接口：用简单入口让使用者知道何时使用、如何进入，无需先了解内部全部细节。用于文档管理，就是入口只说明“解决什么问题、什么时候读、去哪里找”，通过 Markdown 链接指向当前主源，正文按需读取、不在各处复制。

文件夹和单份文档都按这两个原则组织：内部内容完整、职责集中，外部入口简明；根据实际内容决定是否拆分。

流程

1. 了解现状。 阅读现有入口、文档和相关对话，确认常见任务、资料用途与已有主源，明确本次是规划、整理还是只读审查。
2. 按职责归类。 盘点全项目文档，将服务同一职责、经常一起查阅或更新的资料放在一起。优先复用已有目录；项目扩大后，若一个目录混入多种职责、相关资料散落多处，或读者需要反复跳转才能找齐资料，再考虑拆分、归并或调整归属。说明调整后各目录负责什么，一份文档能说清时无需拆目录。
3. 确定主源与入口。 同一主题、同一适用版本只有一份当前有效正文；按已确认的生效与替代关系判断，草稿标明状态，已被替代的资料沿用项目归档位置并注明替代链接，仍受支持的旧版本保留适用范围，不只按日期归档。入口链接当前正文；资料多时设简短索引，少时直接链接。将实际路径交给 agent-entrypoints 接入 Agent 入口与 CLAUDE_MAP.md，说明读取条件，正文只维护一处。
4. 验证并交付。 用一两个真实任务从入口找到适用正文，检查归属、重复主源、历史误用、断链与多余跳转。规划交付路径、职责和取舍；整理在授权内落实归位、归档及引用更新，保留有效内容与历史；只读审查仅给问题和建议。说明验证结果与缺口。

例子

订单导出的当前 Spec 可放 docs/specs/order-export.md，设计说明放 docs/design/order-export.md，被替代的 Spec 放 docs/specs/archive/ 并链接当前版本。CLAUDE_MAP.md 分别指向需求和设计：“确认导出行为时读 Spec；理解实现方案时读设计说明”。这些是示例路径，采用项目实际目录；文件少时直接链接正文。