vibe-coding-docs
Overview
In AI-assisted development, the model does not persistently remember project context between sessions. Each generation depends on the context supplied at that moment. Documentation makes that context explicit and durable: it is the standing protocol between the human and the model, and the memory that survives session boundaries. This skill keeps that protocol alive and verifiable so that generated code stays correct, consistent, and aligned with settled decisions. It is a self-contained, general-purpose methodology tool and does not derive from or endorse any specific external source.
When to use
- Starting a new AI-assisted coding project and needing stable, shared context.
- After code changes, to verify that the documents still match reality.
- When a non-obvious trade-off is made and should not be re-litigated later.
Trigger phrases:
| Intent | 中文 | English |
|---|---|---|
| init | 搭文档骨架 / 初始化项目文档 / vibe coding 初始化 | set up project docs / scaffold project documentation |
| sync | 检查文档是否过期 / 文档和代码对一遍 | check docs against code / are my docs stale |
| decide | 记录一个决策 | record a decision / log an ADR |
Quick start
- init — "搭文档骨架": scan the repo, then write the five documents into the project root or
docs/. - Fill the decisive fields — boundaries ("what we don't do"), per-runtime allowed/forbidden APIs, error/degradation policy. These are what stop the model from writing wrong code; see
references/walkthrough.mdstep 1. - Write code — the documents replace repeated explanation. No need to restate constraints each session.
- sync — "文档和代码对一遍": run the checker after interface / dependency / runtime changes.
- decide — "记录一个决策": one ADR entry per non-obvious trade-off.
A complete worked example (real commands and real output) is in references/walkthrough.md.
Commands
1. init — scaffold the five-document system
Create the five documents at the project root or in a docs/ folder:
PROJECT.md— what the project is, its boundaries, stack, directory layout, and inviolable principles. Sets the model's baseline context before any task begins.ARCHITECTURE.md— runtime inventory, which APIs are allowed or forbidden per runtime, pure-function requirements, and network/storage/DOM conventions, plus known environment pitfalls.CONVENTIONS.md— naming, function responsibility, error handling, logging, type habits, reuse rules, and degradation policy.STATUS.md— a per-platform/module status tracker (verified / code-only / known-issue / skipped) with reasons.DECISIONS.md— an ADR-style decision log capturing why alternatives were rejected.
To scaffold, read the matching template from references/<name>.md and write it into the project, replacing placeholders with project-specific facts. Keep templates explicit and task-oriented, not prose-heavy. When the project spans multiple runtimes (browser / Service Worker / Node / Edge / extension), tailor ARCHITECTURE.md to each one.
2. sync — reconcile documents against code
Run the bundled checker (standard library only, cross-platform):
python <skill>/scripts/reconcile.py <project-root> [options]
It reports by severity, and every finding carries a "what to do next" hint:
| Severity | Meaning | Typical findings |
|---|---|---|
| HIGH | Blocking — fix first | document system not initialized, document unreadable, broken references |
| MEDIUM | Should fix | missing document, reference path not found, document possibly stale |
| LOW | To-do | unresolved placeholders (TODO / 待填 / {...}), same-day staleness |
| INFO | FYI | STATUS entries flagged known-issue / skipped / code-only, encoding suggestions |
Options: --json (machine-readable, for CI), --stale-days N / --stale-hours N, --ignore SUBSTR (repeatable), --strict (treat MEDIUM as failure), --max-files N, -q.
Exit codes: 0 no HIGH; 1 has HIGH (or MEDIUM with --strict); 2 bad argument / environment.
Exit code 0 does not prove the documents are correct — the checker only verifies mechanical facts (presence, placeholders, path validity, freshness). Confirm semantic accuracy yourself.
Suppress false positives inline, inside the document:
reconcile:ignore— skip this linereconcile:ignore-next-line— skip the next linereconcile:ignore-file— skip the whole file (place near the top)
Use the output to update the affected documents, then re-run after fixes.
3. decide — record a decision
Append an ADR entry to DECISIONS.md using the format in references/decisions.md: background, decision, alternatives considered, why alternatives were rejected, impact. This prevents the model from re-deriving discarded solutions and the team from re-litigating settled choices.
Boundaries — what this skill does not do
- Does not write or refactor source code. It defines constraints; code changes stay with you or a normal coding turn.
- Does not run tests, builds, or linters, and does not touch git.
- Does not access the network. It reads and writes only inside the project directory you point it at.
- Does not convert documents (no PDF / docx / HTML export) and does not publish anything.
- Does not replace a README. A README addresses users (how to install and run); these five documents address collaborators (what must not change, what was already rejected).
- Does not replace an issue tracker. Issues are tasks that close; these documents are constraints that persist.
- Does not edit documents by itself.
syncdiagnoses only — every edit is explicit. - Does not cover a monorepo in one pass. Run it once per package root.
Anti-patterns — the short list
Full list with fixes, plus a 14-question FAQ, in references/antipatterns.md. The costliest ones:
| Don't | Why it hurts |
|---|---|
Leave [待填] placeholders in place |
The model may treat every listed option as available and generate cross-runtime code that cannot run |
| Let PROJECT.md grow past ~150 lines | It is read at every session start, consuming the context budget the real constraints need |
| Write only what to do, never what not to do | With no explicit ban the model optimizes for "it runs" — e.g. reaching for DOM inside a Service Worker |
| Record a decision without the rejected alternatives | The entire value of an ADR is in the rejected options; without them the same debate repeats next session |
Let STATUS 🟡 entries age indefinitely |
The unverified zone rots and stops being read, then bites during a demo or delivery |
| Write secrets, internal IPs, or client names into documents | Documents enter the model context wholesale — treat anything written there as externalized |
| Put documents in a temporary session folder | They are lost next session; the whole point is surviving session boundaries |
Treat a green sync as proof of correctness |
It checks mechanical facts only, never whether the content matches reality |
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
[HIGH] no documents found |
Never initialized, or documents sit outside the searched dirs | Write the five documents into the project root or docs/ (also searched: .docs/, doc/, .doc/) |
[HIGH] ... unreadable |
Encoding mismatch, permissions, or the file vanished mid-run | Save as UTF-8 (GB18030 / UTF-16 are decoded as a fallback, UTF-8 is still recommended); check permissions; re-run |
[MEDIUM] missing document |
Only part of the five exists | Fill in the rest, or log in DECISIONS.md why this project does not need it |
[MEDIUM] reference path not found |
The file was renamed or moved, or the line is only an example path | Update the path — or mark the example with reconcile:ignore-next-line on the line above |
| A reference looks correct but is reported broken | Paths are resolved against both the project root and the document folder | Check actual casing and nesting; if it is an example, add an ignore marker |
[MEDIUM] ... possibly stale |
Source files are newer than the document | Re-read the document and update what changed; if nothing changed, refresh STATUS.md's "last sync" timestamp only |
[MEDIUM] STATUS has known-issue modules |
A module is marked as a known issue | Confirm whether it is fixed; if so set it verified and state how verification was done |
[LOW] unresolved placeholders |
Template fields never filled | Replace with real content, or delete the whole line/section — do not leave it blank |
[INFO] non-UTF-8 encoding |
Document saved as GB18030 / UTF-16 | Convert to UTF-8 so the text does not turn to mojibake in another editor |
| Exit code 2 | Root path missing, not a directory, or unreadable | Check the path, pass the project root rather than a single file, verify permissions |
| Scan feels slow on a large repo | Tens of thousands of source files | Raise --max-files, or exclude trees with --ignore |
Principles for the documents
- Be explicit, not elegant. State hard constraints as rules, not suggestions.
- Face the task, not the reader. State what to change, what not to change, what can be called, what must not be relied on, what the result should look like, and how errors are handled.
- Stay in sync. A stale document misleads more than its absence, because the model treats documents as established fact.
- Keep documents retrievable. Clear structure lets both humans and the model locate the right rule quickly.
Resources
references/project.md,references/architecture.md,references/conventions.md,references/status.md,references/decisions.md— document templates.references/antipatterns.md— what not to do (content, process, placement) and a FAQ.references/walkthrough.md— end-to-end worked example with real commands and output.scripts/reconcile.py— documentation/code drift checker (standard library only).
