# [MGMT-STD-001] 项目文档结构与索引铁律规范

| 项 | 值 |
| --- | --- |
| 文档类型 | 工程治理标准（STD） |
| 适用范围 | 本仓库全部文档 + 所有由 AI 生成/维护文档的行为 |
| 强制级别 | 铁律（违反即判定不合规，必须整改） |
| 编号规则 | **由执行 AI 根据目标目录现有文件序列动态决策**，本规范严禁写死任何具体编号格式 |
| 状态 | 定稿 |

---

## 0. 自调查：文档散落与规范僵化的根源

本规范源于对真实工程现状的调查，三类痛点均在本仓库实证命中：

### 痛点一：根目录被自由散落的说明性文件污染
项目根目录除 README 外，堆砌了大量自由散落的说明/日志文件，污染入口视野，使新读者与 AI 无法第一眼锁定权威入口。本仓库实证违规样本（非平台强制文件、属自由散落说明文档）：
`eco_arch_log.md`、`integration_ux_log.md`、`lazy_load_log.md`、`nightly_update_log.md`、`khy.md`。

### 痛点二：docs/ 子目录文件平铺，无总领索引
`docs/` 顶层虽有 `00_INDEX_文档索引.md`，但其下每个分类子目录内部文件直接平铺，**无一存在排序首位的总领索引文件**：
`01_INIT_立项/` 直接由 `[INIT-PRD-001]` 起头，`03_DESIGN_设计/` 直接由 `[DESIGN-ARCH-001]` 起头，`05_TEST_测试/` 直接由 `[TEST-RPT-001]` 起头。AI 截取上下文时无总领入口可依，只能盲扫全目录。

### 痛点三：在规范/提示词中写死编号与命名，导致僵化冲突
本仓库已自然演化出**两套并存**的命名体系：顶层用数字前缀（`00_INDEX_`、`NN_分类_`），子目录用方括号类型码（`[TYPE-SUB-NNN]`，如 `[MGMT-PLAN-007]`、`[DESIGN-ARCH-031]`）。任何在规范或系统提示词中写死单一编号格式（如强制 `00-`、`_index`）的做法，必然与上述既有惯例之一冲突，且剥夺 AI 感知目录上下文、做出最合理决策的能力。**因此编号与命名规则严禁写死，必须下放给 AI 动态决策。**

---

## 第一章 根目录物理隔离铁律（除 README 外零散落）

**第 1.1 条（唯一入口）** 项目根目录**仅允许** `README.md`（及其语言变体，如 `README.zh-CN.md`）作为说明性入口存在。任何规范、指南、设计、报告、计划、日志类说明性文档，**严禁**存放于根目录。

**第 1.2 条（强制收容所）** 所有非 README 的说明性文件，**必须**移入 `docs/` 目录，并按内容分类归入对应子目录。严禁以"临时""根目录方便"为由滞留根部。

**第 1.3 条（平台强制文件封闭白名单）** 仅以下因平台/工具链识别而**必须**位于根目录的文件获得豁免，白名单**封闭、严禁扩张**，且严禁向白名单文件内塞入业务说明内容：
`LICENSE`、`CHANGELOG.md`、`CONTRIBUTING.md`、`SECURITY.md`、`CODE_OF_CONDUCT.md`、`AGENTS.md`、`CLAUDE.md`、`khy.md`（KHY 平台项目级指令文件，被工具链按根路径强制加载，与 `AGENTS.md`/`CLAUDE.md` 同类）、以及构建/包管理器强制的清单文件（如 `package.json`、`pyproject.toml`）。
白名单之外的任何说明性 `.md`/`.txt`，一律适用第 1.1、1.2 条。

> **【强制校验点 CP-1】** 任何文档生成或移动后，若该文件存于根目录、且非 `README.md`（含其语言变体）、且不在第 1.3 条封闭白名单内，**判定为违规**，必须立即收容进 `docs/` 对应子目录。

---

## 第二章 docs/ 分类与首文件索引制度

**第 2.1 条（首文件索引铁律）** `docs/` 下每个分类子目录，**必须**存在且仅存在一个"索引总领性文件"，作为该分类的唯一入口。无索引的子目录判定为不合规目录。

**第 2.2 条（排序首位铁律）** 该索引文件在目录的自然排序（字典序）中**必须**绝对居于首位，确保 AI 与人类进入目录时首先读取到它。任何业务文档的排序**严禁**先于索引文件。

**第 2.3 条（决策下放 —— 本规范核心）**
索引文件的具体命名格式、前缀、编号体系，以及目录内其他业务文档的编号规则，**严禁**在本规范及任何系统提示词中写死。执行任务的 AI **必须**：
1. **必须**先读取目标目录的现有文件序列，感知其既有命名惯例（前缀风格、类型码、序号位宽）；
2. **必须**自行决策最合理、与现有序列逻辑连贯的命名与编号方案；
3. 决策结果**只需**同时满足两项硬约束：**排序绝对首位**与**逻辑连贯（沿用或自然延伸目录既有惯例）**；
4. **严禁**盲目套用任何固定格式（如一律 `00-`、一律 `_index`），**严禁**因套用固定格式而与目录既有惯例产生冲突。

> 示例（说明决策机制，非强制格式）：若 AI 感知到本仓库顶层惯例为数字前缀 `00_INDEX_`，则在子目录沿用同族数字前缀以保证排序首位与连贯，即为一次合规的动态决策；该决策结果不得被反向固化为本规范的强制条文。

---

## 第三章 索引文件的结构化约束（机器可读）

每个索引总领文件**必须**严格遵循以下三段式结构化模板，**严禁**以大段长文叙述替代结构化内容：

**第 3.1 条（强制头部）** **必须**包含该分类的宏观说明：用一段话界定本分类的内容边界（收什么、不收什么）。

**第 3.2 条（强制主体）** **必须**包含文件清单表格，字段**必须**至少含：

| 文件名(含编号) | 核心职责(10字内) | 状态(草稿/定稿) |
| --- | --- | --- |

**第 3.3 条（强制尾部）** **必须**包含跨分类关联指引：指明与本分类强相关的其他 `docs/` 子目录及其入口。

> **【强制校验点 CP-2】** 索引文件**严禁**出现大段长文，**必须**严格符合三段式模板。
> **【强制校验点 CP-3】** AI 每生成或移动一篇业务文档后，**必须**同步回写更新对应目录的索引文件（增/改对应表格行），**严禁**只落业务文档而不更新索引。
> **【强制校验点 CP-4】** AI **严禁**在无索引文件的子目录下直接生成业务文档；**必须**先生成符合本章模板的索引文件，再生成业务文档。

---

## 第四章 强制校验点汇总（合规判定清单）

| 编号 | 校验点 | 违规判定 |
| --- | --- | --- |
| CP-1 | 根目录非 README、非白名单的说明性文件 | 违规，必须收容 |
| CP-2 | 索引文件偏离三段式结构化模板 | 违规，必须重写 |
| CP-3 | 生成业务文档后未回写索引 | 违规，必须补写 |
| CP-4 | 在无索引子目录下生成业务文档 | 违规，必须先建索引 |
| CP-5 | 索引文件未居目录排序首位 | 违规，必须重命名至首位 |
| CP-6 | 规范/提示词中写死具体编号格式 | 违规，必须改为 AI 动态决策 |

---

## 第五章 AI 预加载提示词附录（AI_SYSTEM_PROMPT_APPENDIX）

下列文本为本规范提炼的可粘贴系统提示词附录，只声明约束目标、不声明实现细节，**严禁**出现任何具体编号格式：

```text
【文档结构与索引铁律】
1. 根目录严禁放置除 README.md 外的任何说明性文件，必须归入 docs/ 对应子目录。
2. docs/ 下的每个子目录必须存在一个“索引总领性文件”作为分类入口，且必须在自然排序中居于首位。
3. 文件编号与索引文件命名由你根据目录现有文件序列和项目惯例动态决策，确保逻辑连贯与排序首位，禁止盲目套用固定格式。
4. 严禁在无索引文件的子目录下生成业务文档（必须先生成索引）。
5. 新增文档后，必须同步更新该目录的索引总领文件。
```

---

## 附录 A：编号规则归属声明

本规范对编号与命名仅设两条硬约束——**排序首位**与**逻辑连贯**；其余一切（前缀、类型码、序号位宽、索引文件名）**一律由执行 AI 依据目标目录现有文件序列动态决策**。本规范正文及配套系统提示词**均未、且严禁**写死任何具体编号格式（如 `00-`、`01-`、`_index`）。

## 附录 B：跨分类关联指引

- 本规范所属分类：`docs/08_MGMT_项目管理/`（工程治理标准）。
- 文档总入口：`docs/00_INDEX_文档索引.md`。
- 文档排版语义与样式分离规范：参见 `docs/03_DESIGN_设计/` 中的 `[DESIGN-ARCH-023]`。
- 项目元数据可维护性（`.ai/` 种子文档）：参见仓库根 `CLAUDE.md` 指向的 `.ai/` 体系。
