Agent Notes (Decision Governance)
Relevant source files
The following files were used as context for generating this wiki page:
Agent Notes serve as the persistent decision-making ledger for the freebuff-proxy project. This system ensures that non-trivial changes—including behavioral modifications, architectural shifts, and cross-file contracts—are documented within the same commit as the source code change. The governance model mandates that developers read relevant notes before modifying protected code to prevent the re-introduction of previously rejected patterns.
Sources: CLAUDE.md:105-106, AGENTS.md:105-106
Governance Principles
The project enforces a strict set of rules for managing and creating notes to maintain historical accuracy and efficiency.
Mandatory Documentation
You must add or update a note in the same commit whenever you make a non-trivial change. These changes include architectural shifts, process modifications, or changes to persistent data formats. If a source code change is protected by the governance system, the gate check will fail if a corresponding note is missing.
Sources: CLAUDE.md:105-111, AGENTS.md:105-111
Note Atomicization and Linking
Each note must focus on exactly one decision. You are prohibited from repurposing an existing note to describe a different decision; instead, you must write a new note and link it to the old one if it supersedes it.
Sources: CLAUDE.md:108-109, AGENTS.md:108-109
Alternative Analysis
Every active note must include a ## Alternatives considered section. This section must explicitly address at least two options:
- Doing nothing.
- Reusing existing implementation patterns.
Sources: CLAUDE.md:110, AGENTS.md:110
Implementation and Storage Structure
Agent Notes are stored in specific directories within the .agents/ folder. The system distinguishes between active decisions, archived records, and specialized skill instructions.
| Path | Purpose | Governance Level |
|---|---|---|
.agents/notes/ | Primary location for active decision notes. | High (Enforced by gates) |
.agents/notes/archived/ | Frozen historical records. Modifications and formatting are prohibited. | Immutable |
.agents/notes/NOTE-EXEMPT.md | Registry of specific code changes exempted from note requirements. | Administrative |
.agents/skills/ | Instructions for specialized agent behaviors. | Functional |
Sources: CLAUDE.md:107-112, scripts/gates/checks/style/style.ts:98-103
Decision Flow Diagram
The following diagram illustrates the lifecycle of a decision and its documentation requirement during the development process.
The diagram shows that non-trivial changes trigger a mandatory note creation process before final verification and commitment.
Sources: CLAUDE.md:105-112, AGENTS.md:105-112
Verification and Automation
The project utilizes automated gates to ensure compliance with the Agent Notes governance model.
Note Verification
The command npm run verify-notes acts as a gatekeeper. It checks for:
- Note Presence: Ensures non-exempted protected source changes have accompanying notes.
- Formatting Consistency: Validates the structure of the notes.
- Reference Integrity: Ensures that internal links between notes and documents are not broken.
Sources: CLAUDE.md:111, AGENTS.md:111, scripts/AGENTS.md:10
Style and Text Governance
Notes and documentation are subject to text quality gates. These gates use a "ratchet" mechanism stored in .gates/style-baseline.json to prevent the introduction of specific text artifacts.
- Prohibited Content: Emoticons, emoji, and dingbats are banned to maintain terminal and CI log consistency.
- Punctuation: Only ASCII punctuation is allowed in comments and documentation. Full-width (CJK) punctuation is strictly limited by the baseline ratchet.
- Markdown in Comments: While allowed in documentation files, Markdown syntax (tables, headers, bolding) is prohibited within source code comments to reduce noise.
Sources: scripts/gates/checks/style/style.ts:5-40, scripts/AGENTS.md:14-18
Document Cross-Referencing
Agent Notes function alongside other documentation types. The system identifies "Sole Sources" (真源) to prevent conflicting information across the repository.
This diagram represents the audit process that prevents multiple documents from claiming to be the primary authority for a single technical topic.
Sources: scripts/gates/checks/doc/check-docs.ts:10-15, scripts/gates/checks/doc/check-docs.ts:133-145
Documentation Constraints
Notes must avoid "why" explanations in code comments. Instead, the project policy dictates that:
- Code Comments: Explain what the code does.
- Agent Notes/Docs: Explain why a decision was made, linked from the code.
Sources: CLAUDE.md:79-80, AGENTS.md:79-80
Summary
Agent Notes (Decision Governance) provides a structured, automated framework for capturing the "why" behind the freebuff-proxy project's evolution. By mandating documentation within the same commit as code changes and enforcing these requirements through CI gates, the project maintains a high-fidelity audit trail that informs future development and prevents the repetition of architectural mistakes.
Sources: CLAUDE.md:105-112, scripts/AGENTS.md:10-20