How we cultivate and maintain our knowledge garden
Last Updated: 2026-01-05
The .claude/ directory is our knowledge garden - a living collection of patterns, architecture decisions, troubleshooting guides, and quick references that grow as we build.
Unlike traditional documentation that becomes stale, our garden:
- Grows organically as we discover patterns
- Stays relevant through continuous cultivation
- Captures context that code comments can't
- Guides decisions for future work
.claude/
├── INDEX.md # Garden map (start here)
├── architecture/ # System design decisions
│ ├── data-flow.md
│ ├── api-design.md
│ └── database-schema.md
├── patterns/ # Reusable solutions
│ ├── llm-caching.md
│ ├── edit-tracking.md
│ └── error-handling.md
├── quick-references/ # Fast lookups
│ ├── baseball-api.md
│ ├── api-endpoints.md
│ └── environment-vars.md
└── troubleshooting/ # Problem solutions
├── database-connection.md
├── docker-issues.md
└── type-errors.md
Add when: You make a significant design choice
Example:
- Why we chose Fastify over Express
- How we structure the monorepo
- Database schema design rationale
Location: .claude/architecture/
Add when: You solve a problem that might recur
Example:
- How we cache LLM responses
- How we track manual edits
- How we handle API errors
Location: .claude/patterns/
Add when: You need to look something up repeatedly
Example:
- API endpoint specifications
- Environment variable list
- Common commands
Location: .claude/quick-references/
Add when: You solve a non-obvious problem
Example:
- Database connection issues
- Docker networking problems
- TypeScript type errors
Location: .claude/troubleshooting/
Every garden document should have:
- Title - Clear, descriptive
- Context - Why this matters
- Content - The actual knowledge
- Examples - Show, don't just tell
- Related - Links to connected documents
# Pattern Name
**Context:** Brief explanation of when/why this pattern is used
**Last Updated:** YYYY-MM-DD
---
## The Problem
Describe the problem this pattern solves.
## The Solution
Explain the solution clearly.
## Implementation
Show code examples or step-by-step instructions.
## Trade-offs
What are the pros and cons?
## Related
- [Other Pattern](./other-pattern.md)
- [Architecture Doc](../architecture/related.md)- Be concise - Get to the point quickly
- Use examples - Code snippets, diagrams, real scenarios
- Stay current - Update when things change
- Link liberally - Connect related concepts
- Explain why - Not just what, but why
Weekly:
- Review recent changes
- Add new patterns discovered
- Update outdated information
Monthly:
- Check for dead links
- Consolidate similar documents
- Archive obsolete content
Quarterly:
- Review entire garden structure
- Reorganize if needed
- Update INDEX.md
Healthy:
- Documents are under 400 lines
- Links work and are relevant
- Examples are current
- Information is easy to find
Needs Attention:
- Documents over 400 lines (split them)
- Broken or circular links
- Outdated examples
- Duplicate information
Keep directory structure flat. Two levels max:
.claude/patterns/✅.claude/patterns/frontend/components/❌
If a document exceeds 400 lines, split it:
api-design.md→api-design-rest.md+api-design-graphql.md
Don't copy information. Link to the source:
- "See API Design" ✅
- Copy-pasting the same content ❌
Examples beat explanations:
// Good: Show the pattern
const result = await cache.getOrSet(key, () => fetchData())Explain the "why" not just the "what":
- "We cache LLM responses because they're expensive and slow" ✅
- "This function caches responses" ❌
The INDEX.md is the map of the garden. It should:
- List all documents with brief descriptions
- Group by category (architecture, patterns, etc.)
- Highlight key documents for newcomers
- Stay updated as the garden grows
Update INDEX.md whenever you add or remove documents.
CONSTITUTION.md → Core values (what we believe)
|
VISION.md → Goals (where we're going)
|
.claude/ → Knowledge (what we know)
|
PLAN.md → Tasks (what we're doing)
- CONSTITUTION.md - Principles and values (rarely changes)
- VISION.md - Long-term goals (evolves slowly)
- CLAUDE.md - Technical overview (updates with major changes)
- .claude/ - Detailed knowledge (grows continuously)
- PLAN.md - Current work (updates frequently)
# LLM Response Caching
**Context:** LLM API calls are expensive ($) and slow (seconds). We cache responses to improve performance and reduce costs.
**Last Updated:** 2026-01-05
---
## The Problem
Generating player descriptions via OpenAI:
- Costs $0.002 per request
- Takes 2-3 seconds
- Same stats = same description
## The Solution
Cache descriptions based on a hash of player stats:
```typescript
const statsHash = hashStats(player.stats)
const cached = await db.playerDescription.findUnique({
where: { playerId, statsHash }
})
if (cached) return cached
const description = await generateDescription(player)
await db.playerDescription.create({ playerId, statsHash, description })Pros:
- Fast subsequent requests
- Reduced API costs
- Consistent descriptions
Cons:
- Storage overhead
- Cache invalidation complexity
- Stale descriptions if stats change
### Bad Document: Too Vague
```markdown
# Caching
We use caching to make things faster.
## How
Cache stuff in the database.
# Search for a topic
rg "pattern name" .claude/
# List all documents
fd -e md . .claude/
# Check document length
wc -l .claude/patterns/*.md# Find broken links (manual check)
rg '\[.*\]\(.*\.md\)' .claude/After adding documents, regenerate the index:
# List all documents with descriptions
fd -e md . .claude/ -x head -n 3 {}The garden is alive. It grows, changes, and evolves with the project.
- Don't be precious - Update freely
- Don't be lazy - Keep it current
- Don't be verbose - Stay concise
- Don't be cryptic - Explain clearly
The best garden is the one that's used.
- CONSTITUTION.md - Our values
- VISION.md - Our goals
- PLAN.md - Our work
- CLAUDE.md - Technical overview
- .claude/INDEX.md - Garden map