XingXuan-Sivan 项目文档体系
概述
把项目的文档与工程规范整理成一套可被 AI 高效消费的体系：目录结构、元数据、规范分片、AI 路由入口。
三条硬约束贯穿始终：不覆盖任何已有正文、不自动移动任何文件、不建空目录或占位文档。
目录结构是默认规则，不是铁律。 可以少建（不需要的目录不建），也可以新增（出现没提到的文档类型时，
按 references/structure.md 的加法规则判定归属）。
模式判定
| 模式 | 判定条件 | 做什么 |
|---|---|---|
| M1 初始化 | 新项目，或首次开发任务且无 docs/ |
建立体系 |
| M2 纳管 | 已有 docs/，或根目录有散落 Markdown |
盘点出方案，逐项确认后执行 |
| M3 仅规范 | 用户只要编码或 Git 规范 | 只处理 standards/ |
判不准就先问。M1 与 M2 差别很大，方向做错会浪费一整轮。
M1：初始化
- 探测技术栈与项目形态——读
package.json、pom.xml、pyproject.toml、Cargo.toml等 - 读
references/structure.md，算出必备集与按需集 - 必备集直接建；按需集整理成「拟建目录 + 职责 + 启用理由」清单，一次性请用户确认
- 建
docs/，用assets/templates/_docs-readme.md生成docs/README.md，删掉指向未启用目录的条目 - 用户要规范时：读
references/standards.md，按技术栈选分片拷入docs/development/standards/，并删除 frontmatter 里的applies_when - 配自动化：读
references/automation.md，拷入assets/automation/index-generation.md；按栈选一个发布记录分片。索引默认自动生成，不手写 - 用
assets/templates/_agents.md生成根AGENTS.md；已存在则追加合并，不替换 - 启用了 ADR 等长周期文档时，按
assets/templates/建docs/templates/ - 读
references/root-readme.md，用assets/templates/_root-readme.md生成根README.md——它是产品门面，写法与文档不同；已存在则一字不改。根CHANGELOG.md不在此步创建——它归发布记录工具生成 - 跑
gen_index.py生成所有索引区，再跑自检 - 报告：建了什么、为什么、下一步该写什么
M2：纳管
完整流程见 references/retrofit.md。要点：
- 只读盘点——不改任何文件
- 出四类方案：保留原地 / 建议移动 / 建议合并废弃 / 明确不管
- 逐项确认，只执行确认过的
- 执行：
git mv→ 全局搜索并修复相对链接 → 按映射表补 frontmatter → 建目录 README - 旧到新路径映射表写进
docs/README.md末尾 - 重新生成索引，再跑自检并报告
开工前先确认工作区干净。
M3：仅规范
- 读
references/standards.md，判断用哪种来源：拷分片 / 从现状反向提取 / 合并 - 建
docs/development/standards/，写入选定的分片 - 更新
AGENTS.md的路由行；没有AGENTS.md就从assets/templates/_agents.md生成
安全铁律
- 不覆盖、不改写任何已有正文
- 不移动或重命名未确认的文件；移动必须走
git mv - 已有
AGENTS.md/CLAUDE.md一律追加合并，绝不替换 - 不建空目录、不建占位文档
- 外部工具目录识别但不动
- 目标文件已存在就停下报告，不静默跳过
- 迁移前要求工作区干净，不干净就先让用户提交或 stash
违反规则的字面意思就是违反规则的精神。
自检
生成或修改完成后必须运行：
# 生成索引区（改造过文档结构后一定要跑）
python <skill目录>/scripts/gen_index.py <项目根目录>
# 结构校验；若 gen_index.py 在同目录，会顺带检查索引是否同步
python <skill目录>/scripts/verify_docs.py <项目根目录>
error必须修到清零；warning逐条判断AGENTS.md引用的路径必须全部存在——这是最伤的一种坏法，AI 会照它去读- 校验脚本不修改任何文件，只报告
资源导航
| 什么时候读 | 读哪个 |
|---|---|
| 判断目录要不要建、文档该放哪 | references/structure.md |
| 写根 README（产品门面，与文档写法不同） | references/root-readme.md |
| 写 README 或补 frontmatter | references/metadata.md |
| 项目已有文档，要整理 | references/retrofit.md |
| 选规范、加分片、回写模板 | references/standards.md |
| 决定索引与发布记录怎么维护 | references/automation.md |
| 加模板或导入外部模板 | references/resources.md |
| 写 ADR，或发现 ADR 与实现不符 | references/adr.md |
模板在 assets/templates/，规范分片在 assets/standards/，自动化分片在 assets/automation/。
先列目录再取用，不要假设有哪些文件。