project-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Documentation

项目文档

End-to-end documentation lifecycle for PHP/Laravel and Node/TypeScript/React projects. Contains 25 rules across 6 categories covering folder structure, naming conventions, essential files, content quality (including AI-slop detection), cleanup of accumulated junk, and lifecycle. Supports bootstrap mode (set up docs in a new project), audit mode (find what's missing, stale, bloated, or junk), and reference mode (conventions lookup).

适用于PHP/Laravel和Node/TypeScript/React项目的端到端文档生命周期指南。包含6大类共25条规则，覆盖文件夹结构、命名规范、必要文件、内容质量（包括AI垃圾内容检测）、累积垃圾文件清理及文档生命周期管理。支持bootstrap模式（为新项目搭建文档）、audit模式（查找缺失、过期、冗余或垃圾文档）和reference模式（规范查询）。

Metadata

元数据

Version: 1.0.0
Scope: PHP / Laravel + Node / TypeScript / React projects
Rule Count: 25 rules across 6 categories
License: MIT

版本： 1.0.0
适用范围： PHP / Laravel + Node / TypeScript / React项目
规则数量： 6大类共25条规则
许可证： MIT

How to Use This Skill — Three Modes

技能使用方式——三种模式

Mode 1: Bootstrap (new project / missing docs)

模式1：Bootstrap（新项目/缺失文档场景）

When the user asks "set up docs", "what docs does this project need", or starts a new project — walk through the bootstrap steps:

Detect project type (Laravel? React? Both?) —
```
composer.json
```
,
```
package.json
```
,
```
artisan
```
binary
Inventory existing docs — list every
```
.md
```
file with its location and last-modified date
Identify gaps — compare against the Essential Files checklist; report what's missing
Propose folder structure —
```
docs/
```
with sub-folders (
```
architecture/
```
,
```
adr/
```
,
```
guides/
```
,
```
runbooks/
```
,
```
archive/
```
) based on project size
Offer to scaffold templates — README, CHANGELOG, LICENSE, CONTRIBUTING, SECURITY, ADR-0001 — generate with user approval, do not auto-create
Suggest CI gates — markdown-lint, broken-link checker (lychee), CHANGELOG-on-PR enforcement

当用户询问“set up docs”、“what docs does this project need”或启动新项目时，按以下步骤执行：

检测项目类型（Laravel？React？两者兼具？）——通过
```
composer.json
```
、
```
package.json
```
、
```
artisan
```
可执行文件判断
盘点现有文档——列出所有
```
.md
```
文件及其位置和最后修改日期
识别缺失内容——对照必要文件清单，报告缺失的文档
建议文件夹结构——根据项目规模，创建
```
docs/
```
目录及子文件夹（
```
architecture/
```
、
```
adr/
```
、
```
guides/
```
、
```
runbooks/
```
、
```
archive/
```
）
提供模板搭建选项——README、CHANGELOG、LICENSE、CONTRIBUTING、SECURITY、ADR-0001模板，需经用户确认后生成，禁止自动创建
建议CI校验规则——markdown-lint、断链检查工具（lychee）、PR时强制更新CHANGELOG

Mode 2: Audit (existing project cleanup)

模式2：Audit（现有项目文档清理）

When the user asks "audit docs", "clean up markdown", or "what should I delete" — produce a classified ledger.

For each

.md

file in the repo:

KEEP — file is essential and current
UPDATE — file is essential but stale (e.g., README contradicts current setup)
ARCHIVE — superseded but historically useful — move to
```
docs/archive/<year>/
```
DELETE — AI-generated plan files, empty stubs, duplicates, orphaned drafts
MOVE — wrong location or wrong name (e.g.,
```
MyArchitectureNotes.md
```
at root →
```
docs/architecture/overview.md
```
)

Output format:

undefined

当用户询问“audit docs”、“clean up markdown”或“what should I delete”时，生成分类清单。

针对仓库中每个

.md

文件：

保留——文件为必要且内容最新
更新——文件为必要但已过期（例如README与当前配置矛盾）
归档——已被替代但具有历史价值——移动至
```
docs/archive/<year>/
```
删除——AI生成的规划文件、空存根、重复文件、孤立草稿
移动——位置或命名错误（例如根目录的
```
MyArchitectureNotes.md
```
→
```
docs/architecture/overview.md
```
）

输出格式：

undefined

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

文件	最后修改时间	结论	原因	操作
PLAN.md	2026-02-14	删除	AI生成的规划文件，已无引用	rm PLAN.md
README.md	2024-08-01	更新	安装步骤提及已移除的Vite v3	更新安装章节
docs/old-architecture.md	2024-11	归档	已被docs/architecture/overview.md替代	移动至docs/archive/2024/
MyNotes.md	2025-09	删除	个人笔记；不属于项目文档	rm MyNotes.md

Summary

总结

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


**Never auto-delete.** Always surface for user approval first.

保留：X个文件
更新：Y个文件（优先级最高：...）
归档：Z个文件
删除：N个文件
移动：M个文件


**禁止自动删除**。所有操作需先提交用户确认。

Mode 3: Reference (conventions lookup)

模式3：Reference（规范查询）

When the user asks "how should I name this", "where should this go", or references the skill in a code-review context — look up the relevant rule(s) in

rules/

当用户询问“how should I name this”、“where should this go”或在代码评审中引用本技能时，查询

rules/

中的相关规则。

When to Apply

适用场景

Reference this skill when:

Starting a new Laravel or Node/React project and need a docs baseline
Onboarding a project with messy or AI-cluttered markdown files
Setting up
```
docs/
```
folder structure
Naming a new doc file
Deciding whether to delete a
```
PLAN.md
```
/
```
TODO.md
```
/
```
IMPLEMENTATION-SUMMARY.md
```
Adding CI checks for markdown quality
Reviewing a PR that adds or modifies documentation
Quarterly "docs hygiene" sweep

以下场景可参考本技能：

启动新Laravel或Node/React项目，需要文档基准
接手文档混乱或充斥AI生成内容的项目
搭建
```
docs/
```
文件夹结构
为新文档命名
决定是否删除
```
PLAN.md
```
/
```
TODO.md
```
/
```
IMPLEMENTATION-SUMMARY.md
```
添加Markdown质量的CI校验
评审新增或修改文档的PR
季度“文档卫生”清理

Step 1: Detect Project Type

步骤1：检测项目类型

Always check the project stack before recommending specifics. Bootstrap and naming guidance differ slightly per stack.

Signal	Project Type	Notes
`composer.json` + `artisan`	Laravel (PHP)	README should cover `composer install` , `php artisan migrate` , `.env.example`
`package.json` (only)	Node / TypeScript / React	README should cover `npm install` , `.nvmrc` , build scripts
Both present	Laravel + Inertia + React	README covers both PHP and Node setup paths

The rules themselves are mostly stack-agnostic — README format, ADR structure, naming conventions apply to any project.

在推荐具体方案前，务必先检查项目技术栈。不同技术栈的初始化和命名指导略有差异。

识别信号	项目类型	说明
`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结构、命名规范适用于所有项目。

Rule Categories by Priority

按优先级划分的规则类别


structure-
naming-
essential-
quality-
cleanup-
lifecycle-

Priority	Category	Impact	Prefix
1	Structure	CRITICAL	`structure-`
2	Naming	CRITICAL	`naming-`
3	Essential Files	HIGH	`essential-`
4	Quality	HIGH	`quality-`
5	Cleanup	HIGH	`cleanup-`
6	Lifecycle	MEDIUM	`lifecycle-`


structure-
naming-
essential-
quality-
cleanup-
lifecycle-

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

Quick Reference

快速参考

1. Structure (CRITICAL)

1. 结构（关键）

```
structure-root-files
```
— Which files belong at the repo root (README, CHANGELOG, LICENSE, etc.)
```
structure-docs-folder
```
—
```
docs/
```
as the home for everything beyond root files
```
structure-subfolders
```
— Recommended
```
docs/
```
layout: architecture/, adr/, guides/, runbooks/, archive/

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

2. Naming (CRITICAL)

2. 命名（关键）

```
naming-root-files
```
—
```
UPPERCASE.md
```
for conventional root files
```
naming-docs-files
```
—
```
kebab-case.md
```
for files under
```
docs/
```

naming-adr-files

— Numbered prefix:

0001-record-architecture-decisions.md

naming-anti-patterns

— No dates, no

MyNotes.md

, no

tmp/draft/final

markers

```
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 Files (HIGH)

3. 必要文件（高）

```
essential-readme
```
— Every project needs a README with purpose, install, usage, license
```
essential-changelog
```
— Keep-a-Changelog format; one entry per release
```
essential-license
```
—
```
LICENSE
```
file (or
```
LICENSE.md
```
) at repo root
```
essential-contributing
```
—
```
CONTRIBUTING.md
```
when accepting external contributors
```
essential-security
```
—
```
SECURITY.md
```
with vulnerability reporting policy

```
essential-readme
```
— 每个项目都需要包含用途、安装、使用、许可证的README
```
essential-changelog
```
— 遵循Keep-a-Changelog格式；每个版本对应一条记录
```
essential-license
```
— 仓库根目录需包含
```
LICENSE
```
文件（或
```
LICENSE.md
```
）
```
essential-contributing
```
— 接受外部贡献者时需提供
```
CONTRIBUTING.md
```
```
essential-security
```
— 面向互联网的项目需提供
```
SECURITY.md
```
，包含漏洞上报政策

4. Quality (HIGH)

4. 质量（高）

```
quality-conciseness
```
— Cut bloat; length is a cost, not a virtue
```
quality-ai-slop
```
— Detect AI-generated content patterns (filler, sign-offs, generic praise)
```
quality-headings
```
— One H1, no skipped levels, descriptive heading text
```
quality-code-blocks
```
— Language tags, copy-pasteable commands, no untagged blocks
```
quality-links
```
— Descriptive link text (not "click here"), relative paths, no broken links

```
quality-conciseness
```
— 删除冗余内容；文档长度是成本而非优势
```
quality-ai-slop
```
— 识别AI生成内容的特征（填充内容、落款、通用赞美语）
```
quality-headings
```
— 仅一个H1标题，不跳过层级，标题描述清晰
```
quality-code-blocks
```
— 添加语言标签、可复制的命令，禁止无标签代码块
```
quality-links
```
— 链接文本描述清晰（而非“点击此处”），使用相对路径，避免断链

5. Cleanup (HIGH)

5. 清理（高）

```
cleanup-ai-junk
```
— Detect and remove AI-generated plan/summary files
```
cleanup-duplicates
```
— Same content in multiple files; consolidate or delete copies
```
cleanup-orphans
```
—
```
.md
```
files not linked from anywhere; archive or delete
```
cleanup-empty-stubs
```
— Files with TBD / TODO / placeholder content only

```
cleanup-ai-junk
```
— 识别并删除AI生成的规划/摘要文件
```
cleanup-duplicates
```
— 多文件内容重复；合并或删除副本
```
cleanup-orphans
```
— 未被任何地方引用的
```
.md
```
文件；归档或删除
```
cleanup-empty-stubs
```
— 仅包含TBD / TODO / 占位符内容的文件

6. Lifecycle (MEDIUM)

6. 生命周期（中）

```
lifecycle-freshness
```
— "Last verified" dates on architecture docs
```
lifecycle-archive
```
— Superseded docs go to
```
docs/archive/<year>/
```
```
lifecycle-adr-process
```
— ADR creation triggers and lifecycle (proposed → accepted → superseded)
```
lifecycle-changelog-discipline
```
— Add a CHANGELOG entry in the same PR as the change

```
lifecycle-freshness
```
— 架构文档添加“最后验证”日期
```
lifecycle-archive
```
— 已被替代的文档移至
```
docs/archive/<year>/
```
```
lifecycle-adr-process
```
— ADR创建触发条件及生命周期（提议→通过→替代）
```
lifecycle-changelog-discipline
```
— 在提交变更的同一PR中添加CHANGELOG记录

Essential Patterns

核心规范

Standard folder layout

标准文件夹布局

.
├── 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                    # 面向互联网时必填
├── CODE_OF_CONDUCT.md             # 拥有开源社区时必填
├── .github/
│   └── CODEOWNERS                 # 团队所有权配置
└── 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

File naming at a glance

文件命名速览

✓ 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)

✓ 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          # 常规根目录文件需使用大写命名
✗ docs/Architecture/Overview.md    # docs/下文件需使用kebab-case命名
✗ docs/Notes-2025-09-14.md         # 文件名不含日期
✗ MyArchitectureThoughts.md        # 不含第一人称、不使用PascalCase
✗ PLAN.md, TODO.md, TEMP.md        # 临时状态使用问题追踪工具管理
✗ FINAL-deployment-guide-v2.md     # 不含draft/final/v2这类标记

CI: keep markdown honest

CI：保障Markdown文档质量

yaml

undefined

yaml

undefined

.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'

undefined

name: Lint markdown uses: DavidAnson/markdownlint-cli2-action@v23
name: Check links uses: lycheeverse/lychee-action@v2 with: args: --no-progress --exclude-mail './**/*.md'

undefined

How to Use

使用方式

Read individual rule files for detailed conventions and examples:

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

Each rule file contains:

YAML frontmatter with metadata (title, impact, tags)
Brief explanation of why it matters
Incorrect example (anti-pattern)
Correct example (the convention)
Detection / enforcement guidance where applicable

查看单个规则文件获取详细规范及示例：

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

每个规则文件包含：

带元数据的YAML前置内容（标题、影响程度、标签）
规则重要性的简要说明
错误示例（反模式）
正确示例（规范）
适用的检测/执行指导（如有）

References

参考资料

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

包含所有扩展规则的完整指南：

AGENTS.md