Three Documents & Methodology Capture
You ship 30 features, then three months later you want to know: "When was this added? Why was it designed this way? How many times did the approach change?" You can dig through git log all day and never find the answer. The solution is to have AI maintain three documents against strict templates, plus a methodology handbook that captures decisions automatically. Both demos on this page are interactive.
Core division of responsibility: FEATURES answers "where did this feature come from?"; CHANGELOG answers "what changed this time?"; RELEASE_NOTES answers "what does the user get?"; METHODOLOGY answers "how were we thinking?" Each question has its own home, and decisions can survive beyond any single conversation.
The Full Lifecycle of a Feature
The single source of truth for features. Status flow: 🟡 Planned → 🔵 In Development → 🟢 Complete / ⚪ Cancelled. Each feature has a "history" section recording the original requirement, any approach changes with reasoning, and the final implementation. Cancelled features are never deleted—just marked ⚪ with an explanation.
Technical Details of Every Change
Reverse chronological. Each entry uses a table to record: issue/requirement, root cause/approach, scope of changes, affected areas, and status. Type tags: BUG / FEAT / REFACTOR / PERF / DOCS. Must read system time before writing—never fill timestamps from memory; no backfilling allowed.
Changes Users Can Notice
Written for real users, in a completely different voice than CHANGELOG. Every item must answer "what does this mean for me?" Hard rules: no debug features, no technical details, no changes users can't perceive.
Product Decisions & Taste
AI proactively identifies product philosophy, decision logic, and trade-off preferences from conversations, distills them, and writes them in directly. New conversations inherit automatically. Four sections: Product Principles, Design Decision Log, UX Preferences, Anti-patterns.
Projects generate all kinds of information every day. Your triage ability determines whether the document system can actually run. Below are 8 real pieces of information—decide which document each one belongs in.
Every feature in FEATURES has a "History" section. It grows automatically through status transitions: every status change and approach adjustment appends a dated entry. Click the buttons to manually push a feature from planning to live.
Dates in the history are read from your device's system clock. Rule: timestamps must be read from the current system time—never filled in from memory. Even if the approach hasn't changed, you must write an "Initial Requirement" entry.
Each change is recorded in a fixed-field table. AI fills in the fields—no need to think about what to write each time.
## YYYY-MM-DD HH:MM
### [Type] Title Types: BUG / FEAT / REFACTOR / PERF / DOCS
| Field | Content |
|----------------|------------------------------------------------------------|
| Issue/Req | What triggered this change (user feedback / bug / new req) |
| Cause/Approach | Bugs: root cause analysis; Features: technical approach |
| Scope | List of files or modules affected |
| Impact | Existing features that may be affected by this change |
| Status | ✅ Done / ⏳ In Progress / ⚠️ Needs Monitoring |- Debug / internal tooling
- Technical implementation details: module names, file paths, refactors
- Changes users can't perceive
- Developer jargon and technical explanations
- Changes users can notice; each item must answer "what does this mean for me?"
- New features: one sentence on what the user can now do
- Fixes: what was the problem before, and it's now resolved
- Max 3 sentences per item; version numbers follow SemVer
Four-Section Structure
- Product Principles: Core beliefs and product philosophy that recur repeatedly
- Design Decision Log: [Date] decision content, with rationale and context
- UX Preferences: Taste, tendencies, and aesthetic standards for UI/UX
- Anti-patterns: Approaches explicitly rejected, with reasons
Writing Principles
- Distill to essentials; merge similar items; date new entries; don't copy-paste conversation verbatim
- Don't record technical implementation details (that's CHANGELOG's job); don't record one-off temporary decisions
- Triggers: user explains "why we're doing it this way"; user rejects an approach with reasoning; user expresses clear UI/UX preferences; user summarizes lessons in a retrospective
- AI writes it in immediately upon recognition; briefly notifies the user after writing; no permission needed each time
Why keep it in the repository: Design decisions written in Notion or Feishu are useless—AI can't read external documents. A Markdown file inside the project repository is the only way for AI to automatically access context.
Deliverable: a docs/ directory + 3 methodology entries. ① In an active project, create the docs/ directory and have AI initialize the three documents from the templates, backfilling existing features into FEATURES.md; ② Add the documentation rules to your Rule file, make a small change, and verify that AI automatically updates CHANGELOG; ③ Review your recent product discussions and manually write 3 design decisions you've confirmed into METHODOLOGY.md.
Source: open-source repository itshen/xs_vibe_rules, rule-opensource.mdc Chapter 9 "Version Records & Documentation" and Chapter 12 "Product Methodology Capture."