文档结构
深模块:一个单元围绕清晰职责承载完整能力,将相关复杂细节收在内部。用于文档管理,就是让同一职责的资料集中在一个文件夹或文档中,读者能在这里找到解决该类问题所需的内容;“深”不指目录层级多或篇幅长。
浅接口:用简单入口让使用者知道何时使用、如何进入,无需先了解内部全部细节。用于文档管理,就是入口只说明“解决什么问题、什么时候读、去哪里找”,通过 Markdown 链接指向当前主源,正文按需读取、不在各处复制。
文件夹和单份文档都按这两个原则组织:内部内容完整、职责集中,外部入口简明;根据实际内容决定是否拆分。
流程
-
了解现状。 阅读现有入口、文档和相关对话,确认常见任务、资料用途与已有主源,明确本次是规划、整理还是只读审查。
-
按职责归类。 盘点全项目文档,将服务同一职责、经常一起查阅或更新的资料放在一起。优先复用已有目录;项目扩大后,若一个目录混入多种职责、相关资料散落多处,或读者需要反复跳转才能找齐资料,再考虑拆分、归并或调整归属。说明调整后各目录负责什么,一份文档能说清时无需拆目录。
-
确定主源与入口。 同一主题、同一适用版本只有一份当前有效正文;按已确认的生效与替代关系判断,草稿标明状态,已被替代的资料沿用项目归档位置并注明替代链接,仍受支持的旧版本保留适用范围,不只按日期归档。入口链接当前正文;资料多时设简短索引,少时直接链接。将实际路径交给 agent-entrypoints 接入 Agent 入口与
CLAUDE_MAP.md,说明读取条件,正文只维护一处。 -
验证并交付。 用一两个真实任务从入口找到适用正文,检查归属、重复主源、历史误用、断链与多余跳转。规划交付路径、职责和取舍;整理在授权内落实归位、归档及引用更新,保留有效内容与历史;只读审查仅给问题和建议。说明验证结果与缺口。
例子
订单导出的当前 Spec 可放 docs/specs/order-export.md,设计说明放 docs/design/order-export.md,被替代的 Spec 放 docs/specs/archive/ 并链接当前版本。CLAUDE_MAP.md 分别指向需求和设计:“确认导出行为时读 Spec;理解实现方案时读设计说明”。这些是示例路径,采用项目实际目录;文件少时直接链接正文。


