project-docs-system

A Cursor Agent Skill for bootstrapping and maintaining a four-layer documentation system in any software project — agent-readable rules, human-readable encyclopedia, planning backlog, and searchable change archive.

Supports large-scale change archives (74+ records), analogy-driven bugfix docs, and enforced Definition of Done via Cursor rules.

What you get

Layer	Files	Purpose
L1 Agent rules	CLAUDE.md / AGENTS.md	Constraints, shared components, pitfalls
L2 Encyclopedia	docs/APP_GUIDE.md	Architecture, file map, navigation
L3 Planning	docs/BACKLOG.md, docs/ROADMAP.md	Open questions, product plans
L4 Change archive	docs/bug-index.md + docs/bugfix-*.md	Searchable history with analogies
Enforced DoD	.cursor/rules/change-log-required.mdc	Docs required after code changes

Install (Cursor)

Personal skill (all your projects)

cp -R project-docs-system ~/.cursor/skills/project-docs-system

Restart Cursor or start a new chat. The skill appears in the skills menu as project-docs-system.

Per-repo skill (team share)

mkdir -p your-repo/.cursor/skills
cp -R project-docs-system your-repo/.cursor/skills/
git add .cursor/skills/project-docs-system
git commit -m "Add project-docs-system Cursor skill"

Quick start

New project (Bootstrap)

In Cursor chat:

Bootstrap the full documentation system for this repo using project-docs-system.

Or copy bootstrap-prompt.md into the chat.

Existing project (Maintenance)

If CLAUDE.md and docs/bug-index.md already exist, the skill will not re-bootstrap. It will:

• Write bugfix / fix-history records after code changes
• Update shared-component indexes in CLAUDE.md
• Sync APP_GUIDE.md when modules or navigation change

Say:

Maintain docs per project-docs-system — sync shared components and APP_GUIDE.

Package contents

project-docs-system/
├── SKILL.md                 # Main skill (English)
├── bootstrap-prompt.md      # One-shot init prompt
├── reference-example.md     # Mature deployment benchmark
└── templates/
    ├── CLAUDE.md.tpl
    ├── APP_GUIDE.md.tpl
    ├── bug-index.md.tpl
    ├── backlog.md.tpl
    ├── bugfix.md.tpl
    ├── change-log-required.mdc.tpl
    └── spec-design.md.tpl

Trigger phrases

Say this	Agent does
Bootstrap docs with project-docs-system	Full Bootstrap
Initialize project documentation	Full Bootstrap
Remember to write the bugfix doc	Change-log three-step
Check if this needs documentation	Evaluate → write docs if needed

Core ideas

1. Analogy in every change record — non-technical readers can understand why something broke.
2. Index + separate files — bug-index.md is only a table of contents.
3. No duplicate DoD — .mdc is authoritative; CLAUDE.md points to it.
4. CLAUDE short, APP_GUIDE long — what loads every chat stays lean.

License

MIT — use, copy, and adapt freely.