跳转至

文档目录规范

触发场景：新建 / 移动任何 .md 文件时必查。 起因：v0.10.107 之前根目录散落 8 个 md（含开发日志x3 / 更新规则 / v2 改版说明），破坏五层漏斗结构 + MkDocs 引用麻烦。v0.10.108 整改后根只留 4 个标准文件。 目标：让"放哪儿"成为零思考。

SOP 决策树

要建/移一个 .md 文件
  ↓
是 README / CHANGELOG / LICENSE / CONTRIBUTING ?
  ├─ 是 ──> repo 根（GitHub 自动识别）
  └─ 否 ──> 继续 ↓

是给 AI / 工具的入口（CLAUDE.md / .copilot/...）?
  ├─ 是 ──> repo 根（工具约定）
  └─ 否 ──> 继续 ↓

按内容类型分到 docs/ 五层：
  ↓
版本相关日志（开发日志 / 每版本细节）? ──> docs/changelog/
  ↓
工程契约（PRD / API / 数据模型）? ──> docs/specs/{active,done,parked}/
  ↓
知识沉淀（架构 / 字段语义 / 组件用法）? ──> docs/wiki/
  ↓
bug 归档（病灶 / 修法 / 元教训）? ──> docs/issues/
  ↓
操作手册（遇到 X 怎么做）? ──> docs/rules/
  ↓
原始素材（用户原话 / 半成品想法）? ──> docs/raw/{inbox,feedback,conversations,ideas}/

repo 根的合法 .md（白名单 — 只允许这些）

文件 用途 谁看
README.md 项目首页 GitHub 主页访客
CHANGELOG.md 按版本聚合（机器生成） 用户 / GitHub releases / MkDocs
CLAUDE.md 给 AI 的工作入口 Claude Code 工具
LICENSE 开源许可（若有） 法务 / GitHub
CONTRIBUTING.md 贡献指南（若有） 外部贡献者

绝对不能在根：开发日志 / 更新规则 / 设计说明 / bug 笔记 / 临时想法 — 这些全部属于 docs/。

docs/ 一级（每个目录的角色）

目录 内容 文件命名 示例
docs/index.md MkDocs 站点首页 固定 index.md
docs/changelog/ 项目内部日志（每版细节） development-log.md + development-log-archive-*.md docs/changelog/development-log.md
docs/specs/ 工程契约 SPEC-XXX-<英文短标题>.md docs/specs/active/SPEC-007-...md
docs/wiki/ 知识沉淀 <英文短标题>.md（kebab-case） docs/wiki/shared-queue-architecture.md
docs/issues/ bug 归档 XXXX-<英文短标题>.md（4 位 ID） docs/issues/0070-shared-window-orphan...md
docs/rules/ 操作手册 <场景>.md 或 NN-<场景>.md docs/rules/00-meta-rule.md
docs/raw/ 原始素材 YYYY-MM-DD-<描述>.md（按日期） docs/raw/feedback/2026-05-28-xxx.md
docs/_topics/ 自动主题 hub（rebuild 生成） 各 tag.md docs/_topics/scheduling.md
docs/_todo.md 自动待办聚合 固定 (rebuild 生成)
docs/_overview.md 自动概览 固定 (rebuild 生成)

specs/ 子目录

子目录 状态
docs/specs/active/ 进行中（status: approved / in-progress）
docs/specs/done/ 已落地（status: done）
docs/specs/parked/ 暂缓（status: parked + parked_reason）

命名约定（文件名）

必遵守（v0.10.110 起统一英文文件名）

  • ❌ 不用中文（v0.10.110 起 129 文件追溯英文化）
  • ❌ 不用 + / （ / ）（MkDocs URL 编码后丑陋，v0.10.105 清理过 19 个）
  • ❌ 不用空格 / 大写（kebab-case）
  • ✅ 文件名：英文 + 数字 + - + _（kebab-case，URL 安全）
  • ✅ 文章标题（frontmatter title:）：中文 OK（实际显示用）
  • ✅ ISSUE 用 4 位数字 ID 开头：0070-shared-window-orphan.md
  • ✅ SPEC 用 SPEC- 前缀：SPEC-007-feature-name.md
  • ✅ raw/ 用日期前缀：2026-05-28-feature-name.md

推荐

  • 文件名用"主题 + 子主题"短句：SPEC-006-task-delete-data-cascade-confirm.md
  • 不超过 60 字符（含 .md）
  • 用 - 分词（最终 URL 安全）
  • 中文标题放 frontmatter title: 字段（rebuild-docs.py 用此渲染 INDEX）

frontmatter（每个 md 必含）

---
title: <中文短标题>
description: <30 字内描述，便于检索>
tags: [类型, 主题1, 主题2]
created: YYYY-MM-DD
updated: YYYY-MM-DD
type: raw | spec | wiki | issue | rule | index
status: <类型特定>
related:
  - "[[wikilink-1]]"
---

docs:check 会校验必填字段 — 缺会阻止 commit。

移动 / 重命名时的同步

重要：移动 .md 后必须全局更新所有引用：

# 1. git mv 移文件
git mv 老路径.md 新路径.md

# 2. 全局更新引用（脚本 + 手工）
grep -rln "老路径\|老文件名" docs/ scripts/ *.md mkdocs.yml
# → 每个引用文件改成新路径

# 3. 必跑：验证 0 broken link
pnpm docs:check

# 4. 必跑：重生成自动文件
pnpm docs:rebuild
pnpm docs:changelog

反例（v0.10.108 之前的现状）

文件 在哪 问题
~~development-log.md~~ 根 应在 docs/changelog/，MkDocs 要 cp 才能引用
~~开发日志-archive-*.md~~ 根 同上
~~更新规则.md~~ 根 是 rule 类型，应在 docs/rules/version-release-iron-rules.md
~~v2-UI改版说明.md~~ 根 是 SPEC，应在 docs/specs/done/SPEC-000-v2-ui-redesign.md

v0.10.108 全部修正，根从 8 .md 降到 4 .md（README/CHANGELOG/CLAUDE + 可选 LICENSE）。

工具支持

命令 作用
pnpm docs:check broken link + frontmatter 必填校验
pnpm docs:rebuild 重建 INDEX/_todo/_topics（自动）
pnpm docs:changelog 重生成 CHANGELOG.md
pre-commit hook 上述都在 commit 时自动跑

相关