project-docs

项目文档

为 PHP/Laravel 和 Node/TypeScript/React 项目提供端到端的文档生命周期管理。包含 6 个类别中的 25 条规则，涵盖文件夹结构、命名约定、必备文件、内容质量（包括 AI 水文检测）、清理累积的杂项，以及生命周期。支持 引导模式（在新项目中搭建文档）、审计模式（查找缺失、过时、冗长或无用的内容）和 参考模式（查询约定）。

元数据

• 版本： 1.0.0
• 范围： PHP / Laravel + Node / TypeScript / React 项目
• 规则数量： 6 个类别中的 25 条规则
• 许可证： MIT

如何使用此技能 — 三种模式

模式 1：引导（新项目 / 缺少文档）

当用户提出“搭建文档”“此项目需要哪些文档”或开始新项目时 — 按照引导步骤进行：

1. 检测项目类型（Laravel？React？两者都有？）— composer.json、package.json、artisan 二进制文件
2. 盘点现有文档 — 列出每个 .md 文件及其位置和最后修改日期
3. 找出缺口 — 对照必备文件检查清单；报告缺失内容
4. 提出文件夹结构 — 根据项目规模设置包含子文件夹（architecture/、adr/、guides/、runbooks/、archive/）的 docs/
5. 提供模板脚手架 — README、CHANGELOG、LICENSE、CONTRIBUTING、SECURITY、ADR-0001 — 经用户批准后生成，不要自动创建
6. 建议 CI 门禁 — markdown-lint、失效链接检查器（lychee）、强制要求 PR 包含 CHANGELOG

模式 2：审计（清理现有项目）

当用户提出“审计文档”“清理 markdown”或“应该删掉什么”时 — 生成分类清单。

对于仓库中的每个 .md 文件：

• 保留 — 文件必不可少且内容为最新
• 更新 — 文件必不可少但已过时（例如，README 与当前设置相矛盾）
• 归档 — 内容已被取代但具有历史价值 — 移至 docs/archive/<year>/
• 删除 — AI 生成的计划文件、空占位文件、重复文件、无主草稿
• 移动 — 位置或名称不正确（例如，根目录下的 MyArchitectureNotes.md → docs/architecture/overview.md）

输出格式：

## Documentation Audit Ledger

| File | Last modified | Verdict | Reason | Action |
|------|---------------|---------|--------|--------|
| PLAN.md | 2026-02-14 | DELETE | AI-generated plan, no longer referenced | rm PLAN.md |
| README.md | 2024-08-01 | UPDATE | Setup steps reference removed Vite v3 | Update install section |
| docs/old-architecture.md | 2024-11 | ARCHIVE | Superseded by docs/architecture/overview.md | mv to docs/archive/2024/ |
| MyNotes.md | 2025-09 | DELETE | Personal notes; not project docs | rm MyNotes.md |

## Summary
- KEEP: X files
- UPDATE: Y files (top priority: ...)
- ARCHIVE: Z files
- DELETE: N files
- MOVE: M files

绝不自动删除。 始终先提交用户批准。

模式 3：参考（查询约定）

当用户提出“这个该怎么命名”“应该放在哪里”或在代码审查中提及此技能时 — 在 rules/ 中查找相关规则。

适用场景

在以下情况参考此技能：

• 启动新的 Laravel 或 Node/React 项目并需要文档基线
• 接手包含杂乱或被 AI 内容塞满的 markdown 文件的项目
• 设置 docs/ 文件夹结构
• 为新的文档文件命名
• 决定是否删除 PLAN.md / TODO.md / IMPLEMENTATION-SUMMARY.md
• 添加用于检查 markdown 质量的 CI 检查
• 审查新增或修改文档的 PR
• 每季度进行一次“文档卫生”检查

步骤 1：检测项目类型

在提出具体建议前，务必先检查项目技术栈。 不同技术栈的引导和命名建议略有不同。

信号	项目类型	说明
composer.json + artisan	Laravel（PHP）	README 应涵盖 composer install、php artisan migrate、.env.example
仅有 package.json	Node / TypeScript / React	README 应涵盖 npm install、.nvmrc、构建脚本
两者均存在	Laravel + Inertia + React	README 应涵盖 PHP 和 Node 两种设置流程

规则本身大多与技术栈无关 — README 格式、ADR 结构和命名约定适用于任何项目。

按优先级划分的规则类别

优先级	类别	影响	前缀
1	结构	严重	structure-
2	命名	严重	naming-
3	必备文件	高	essential-
4	质量	高	quality-
5	清理	高	cleanup-
6	生命周期	中	lifecycle-

快速参考

1. 结构（关键）

• structure-root-files — 哪些文件应放在仓库根目录（README、CHANGELOG、LICENSE 等）
• structure-docs-folder — 将 docs/ 作为存放根目录文件以外所有内容的位置
• structure-subfolders — 推荐的 docs/ 布局：architecture/、adr/、guides/、runbooks/、archive/

2. 命名（关键）

• naming-root-files — 常规根目录文件使用 UPPERCASE.md
• naming-docs-files — docs/ 下的文件使用 kebab-case.md
• naming-adr-files — 使用编号前缀：0001-record-architecture-decisions.md
• naming-anti-patterns — 不使用日期、MyNotes.md 或 tmp/draft/final 标记

3. 必备文件（高）

• essential-readme — 每个项目都需要 README，说明项目用途、安装、用法和许可证
• essential-changelog — 使用 Keep a Changelog 格式；每个版本对应一条记录
• essential-license — 在仓库根目录放置 LICENSE 文件（或 LICENSE.md）
• essential-contributing — 接受外部贡献者时添加 CONTRIBUTING.md
• essential-security — 添加 SECURITY.md，说明漏洞报告政策

4. 质量（高）

• quality-conciseness — 删除冗余；篇幅是一种成本，而非优点
• quality-ai-slop — 检测 AI 生成内容的常见模式（填充内容、结尾致意、泛泛的赞美）
• quality-headings — 只使用一个 H1，不跳过标题级别，标题文字应清晰描述内容
• quality-code-blocks — 使用语言标签，命令应可复制粘贴，不使用未标注语言的代码块
• quality-links — 使用描述性链接文字（而非“点击这里”）、相对路径，并确保链接有效

5. 清理（高）

• cleanup-ai-junk — 检测并移除 AI 生成的计划或摘要文件
• cleanup-duplicates — 找出多个文件中的重复内容，合并或删除副本
• cleanup-orphans — 找出没有任何链接指向的 .md 文件，并归档或删除
• cleanup-empty-stubs — 找出仅包含 TBD / TODO / 占位内容的文件

6. 生命周期（中）

• lifecycle-freshness — 在架构文档中标注“上次验证”日期
• lifecycle-archive — 将已被取代的文档移至 docs/archive/<year>/
• lifecycle-adr-process — 说明 ADR 的创建触发条件和生命周期（提议 → 接受 → 被取代）
• lifecycle-changelog-discipline — 在包含变更的同一个 PR 中添加 CHANGELOG 记录

必备模式

标准文件夹布局

.
├── README.md                      # required
├── CHANGELOG.md                   # required from first release
├── LICENSE                        # required
├── CONTRIBUTING.md                # if external contributors
├── SECURITY.md                    # if internet-facing
├── CODE_OF_CONDUCT.md             # if open source community
├── .github/
│   └── CODEOWNERS                 # team ownership
└── docs/
    ├── architecture/
    │   ├── overview.md
    │   └── data-model.md
    ├── adr/
    │   ├── 0001-record-architecture-decisions.md
    │   ├── 0002-choose-mysql-over-postgres.md
    │   └── 0003-adopt-inertia-for-spa.md
    ├── guides/
    │   ├── getting-started.md
    │   ├── deployment.md
    │   └── local-development.md
    ├── runbooks/
    │   ├── deploy-production.md
    │   └── incident-response.md
    └── archive/
        └── 2024/
            └── old-architecture-notes.md

文件命名速览

✓ README.md, CHANGELOG.md, LICENSE, CONTRIBUTING.md, SECURITY.md
✓ docs/architecture/overview.md
✓ docs/adr/0007-cache-strategy.md
✓ docs/guides/deployment.md
✓ docs/archive/2024/q3-launch-plan.md

✗ Readme.md, Changelog.md          (use UPPERCASE for conventional root files)
✗ docs/Architecture/Overview.md    (use kebab-case in docs/)
✗ docs/Notes-2025-09-14.md         (no dates in filenames)
✗ MyArchitectureThoughts.md        (no first-person, no PascalCase)
✗ PLAN.md, TODO.md, TEMP.md        (use issue tracker for transient state)
✗ FINAL-deployment-guide-v2.md     (no draft/final/v2 markers)

CI：确保 Markdown 内容规范

# .github/workflows/docs.yml
- name: Lint markdown
  uses: DavidAnson/markdownlint-cli2-action@v23

- name: Check links
  uses: lycheeverse/lychee-action@v2
  with:
    args: --no-progress --exclude-mail './**/*.md'

使用方法

阅读各规则文件，了解详细规范和示例：

rules/structure-root-files.md
rules/naming-adr-files.md
rules/essential-readme.md
rules/cleanup-ai-junk.md
rules/lifecycle-archive.md

每个规则文件都包含：

• 带有元数据（标题、影响、标签）的 YAML frontmatter
• 关于规则重要性的简要说明
• 错误示例（反模式）
• 正确示例（规范）
• 适用时提供检测 / 强制执行指南

参考资料

• Keep a Changelog
• 语义化版本
• 架构决策记录（ADR）
• Diátaxis — 文档框架
• 选择许可证
• Markdownlint
• Lychee — 链接检查工具

完整汇编文档

查看包含所有规则完整内容的指南：AGENTS.md