Three Documents & Methodology Persistence
FEATURES / CHANGELOG / RELEASE_NOTES each covers one dimension; METHODOLOGY preserves product taste
THE QUESTION THIS PAGE ANSWERS
ANSWER FIRSTWhat is the key idea behind “Three Documents & Methodology Persistence”?
FEATURES / CHANGELOG / RELEASE_NOTES each covers one dimension; METHODOLOGY preserves product taste
Turn taste into a behavior the product can repeat. The useful outcome is not a nice opinion. It is a visible rule, a small example, and a way to tell when the experience falls below the bar.
Capture one before-and-after example that shows the quality bar without extra explanation.
Polish that improves the surface while leaving the user's uncertainty untouched.
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."
Turn the feeling in “The Full Lifecycle of a Feature” into a judgment
“Core division of responsibility: FEATURES answers "where did this feature come from?";” points out that AI has lowered the bar for making something usable. The skill readers need is noticing what is wrong and turning that feeling into an actionable requirement.
Watch the user's next action, not just the surface
Turn “The single source of truth for features.” into observable questions: does the user know what happened, what to do next, and how to recover from an empty or failed state? Does the hierarchy make the important information visible first?
- Debug / internal tooling
- Technical implementation details: module names, file paths, refactors
- Changes users can't perceive
Pretty is not the same as usable
Apply “Deliverable: a docs/ directory + 3 methodology entries.” to a second screen or flow. Record one moment of hesitation and the user action after the change; observable behavior is stronger evidence than polish alone.
From “The Full Lifecycle of a Feature” to “Technical Details of Every Change”
“The Full Lifecycle of a Feature” grounds the problem in “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 wi…”. “Technical Details of Every Change” then moves it toward “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 t…”. Together, they show that the lesson is not just a conclusion to remember, but a claim with conditions.
Carry the judgment into the next situation
For experience work, turn abstract impressions into user actions: did the person understand the state, find the next step, recover from an error, and want to continue?
- “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 wi…
- “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 t…
- “The closing point”: Changes users can notice; each item must answer "what does this mean for me?"
The final “The closing point” brings the discussion to “Changes users can notice; each item must answer "what does this mean for me?"”. The useful thing to carry forward is knowing which judgments must be revisited when input, scale, or risk changes.
I turned one judgment from this article into a small experiment I could run today. Knowing what to observe next is more useful than simply remembering the conclusion.
After reading this, I first looked for the conditions behind the idea instead of copying the method into a project. That order made the later trade-offs much clearer.
When this judgment reaches real work, which constraint should be added first? I am curious which step matters most between reading and the first practical attempt.
No discussion on this article yet.