docs-structure git:20261011.1b07eb2A

Immutable. This exact content never changes and is served at /api/v1/blob/bb64a846405235fe.

---
name: docs-structure
description: 规划、整理或只读审查项目文档结构时使用。按职责聚合同类资料，明确当前主源、历史归档与按需读取入口。
---

# 文档结构

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

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

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

## 流程

1. **了解现状。** 阅读现有入口、文档和相关对话，确认常见任务、资料用途与已有主源，明确本次是规划、整理还是只读审查。

2. **按职责归类。** 盘点全项目文档，将服务同一职责、经常一起查阅或更新的资料放在一起。优先复用已有目录；项目扩大后，若一个目录混入多种职责、相关资料散落多处，或读者需要反复跳转才能找齐资料，再考虑拆分、归并或调整归属。说明调整后各目录负责什么，一份文档能说清时无需拆目录。

3. **确定主源与入口。** 同一主题、同一适用版本只有一份当前有效正文；按已确认的生效与替代关系判断，草稿标明状态，已被替代的资料沿用项目归档位置并注明替代链接，仍受支持的旧版本保留适用范围，不只按日期归档。入口链接当前正文；资料多时设简短索引，少时直接链接。将实际路径交给 [agent-entrypoints](../agent-entrypoints/SKILL.md) 接入 Agent 入口与 `CLAUDE_MAP.md`，说明读取条件，正文只维护一处。

4. **验证并交付。** 用一两个真实任务从入口找到适用正文，检查归属、重复主源、历史误用、断链与多余跳转。规划交付路径、职责和取舍；整理在授权内落实归位、归档及引用更新，保留有效内容与历史；只读审查仅给问题和建议。说明验证结果与缺口。

## 例子

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