Learnings
This directory is the system-of-record for durable learnings extracted from completed work.
Policy
- Prefer merging/deduping into existing bullets over adding new near-duplicates.
- Keep each category within the configured bullet budget (default: 30 per category).
- Each learning bullet should end with a source suffix:
*(F024)*for internally-derived learnings, or*(Author, Source Year)*for externally-sourced insights. - Archive overflow in
docs/learnings/archived/rather than growing unbounded. - Use one-line bullets only, starting with
-.
Categories
| Category | File | Scope |
|---|---|---|
| Architecture | architecture.md | System structure, patterns, boundaries |
| Conventions | conventions.md | Naming, file organization, code style |
| Workflow | workflow.md | Process, automation, verification |
| Integrations | integrations.md | APIs, libraries, external systems |
| Gotchas | gotchas.md | Non-obvious behaviors, edge cases |
| Security | security.md | Threats, hardening, secrets |
| Testing | testing.md | Test patterns, fixtures, mocking |
Archive
Learnings that are stale or superseded move to archived/README.md.
Adding Learnings
The compound-engineer agent updates these files after completed features. To add learnings manually:
- Find the appropriate category file
- Add a one-line bullet starting with
- - End with a source:
*(F001)*for feature-derived learnings, or*(Author, Source Year)*for external insights - If category is at budget, merge related learnings or archive stale ones