journaling-codebase-decisions

name	journaling-codebase-decisions
description	Journals architecture decisions, patterns, mistakes, and codebase state. Maintains institutional memory at .claude/journal.md. Use when starting in a new repo, after significant decisions, or when establishing patterns. Triggers include "update the journal", "document this decision", "journal this pattern", "what did we decide", or /journaling-codebase-decisions.

Codebase Journal

A living document system that maintains institutional memory for a codebase—decisions made, patterns established, mistakes learned from, and current state.

Philosophy

Code tells you what, but not why. The journal captures the reasoning, trade-offs, and lessons that would otherwise be lost. It serves as:

1. Context for AI reviewers - Quick onboarding without reading every line
2. Institutional memory - Why decisions were made, not just what was decided
3. Learning repository - Mistakes and lessons that shouldn't be repeated
4. Onboarding guide - New contributors (human or AI) can quickly understand the codebase

Journal Location

Store the journal at .claude/journal.md in the repository root. This location:

• Keeps it with the code it describes
• Makes it discoverable by review-board and other tools
• Travels with the repository

Journal Structure

# [Project Name] Journal

Last updated: [timestamp]

## Overview
[2-3 sentences describing what this project does and its current state]

## Architecture

### High-Level Structure
[Brief description of how the codebase is organized]

### Key Components
- **[Component 1]**: [What it does, where it lives]
- **[Component 2]**: [What it does, where it lives]

### Data Flow
[How data moves through the system]

## Decisions

### [Decision Title] - [Date]
**Context**: [Why this decision was needed]
**Options Considered**:
1. [Option A]: [Pros/Cons]
2. [Option B]: [Pros/Cons]
**Decision**: [What was chosen]
**Rationale**: [Why this option was selected]
**Consequences**: [Known trade-offs or implications]

## Patterns

### [Pattern Name]
**When to use**: [Situations where this pattern applies]
**Implementation**: [How to implement it in this codebase]
**Example**: [Reference to code or brief example]
**Why this way**: [Rationale for this pattern choice]

## Anti-Patterns (Don't Do This)

### [Anti-Pattern Name]
**What it looks like**: [How to recognize this mistake]
**Why it's problematic**: [What goes wrong]
**Instead, do**: [The correct approach]
**Learned from**: [Brief reference to when we learned this]

## Mistakes & Lessons

### [Mistake Title] - [Date]
**What happened**: [Brief description]
**Root cause**: [Why it happened]
**Impact**: [What was affected]
**Lesson**: [What we learned]
**Prevention**: [How to avoid in future]

## Current State

### Active Work
- [Current feature/focus area]

### Known Issues
- [Issue 1]: [Brief description, any workarounds]

### Technical Debt
- [Debt item]: [Why it exists, priority for addressing]

## Dependencies & External Systems

### [Dependency/System Name]
**Purpose**: [Why we use it]
**Key considerations**: [Gotchas, version constraints, etc.]
**Documentation**: [Link to relevant docs]

## Changelog

### [Date]
- [What changed in the journal and why]

When to Update

Automatic Prompts

Claude should prompt to update the journal when:

1. Significant decision made - Architecture choices, library selections, pattern decisions
2. Pattern established - When saying "let's do it this way going forward"
3. Mistake discovered - Bugs that teach something about the codebase
4. Major feature completed - After substantial work that changes the codebase
5. Starting new session - Check if journal exists and is current

Manual Triggers

• /journal update - Review and update the journal
• /journal init - Initialize journal for a new codebase
• /journal decision [topic] - Document a specific decision
• /journal mistake [description] - Document a lesson learned

Integration Points

With Rules and Skills

After updating the journal, consider whether learnings should also become rules or skills:

Journal Entry	Persist as rule/skill?	Where
Codebase-specific decision	Project rule if behavioral	.claude/rules/
Generalizable pattern	User rule if behavioral	~/.claude/rules/
Common mistake to avoid	User rule	~/.claude/rules/
Repeatable workflow	Skill	~/.claude/skills/ or .claude/skills/
Project architecture	No — journal is sufficient	—

Use /wrap at session end to identify what should be persisted.

With Review Board

The review-board skill automatically reads the journal before conducting reviews:

• Provides context without re-reading all code
• Helps reviewers understand decisions and constraints
• Surfaces known issues and technical debt

Initializing a New Journal

When starting work in a repo without a journal:

1. Explore the codebase - Understand structure, patterns, key files
2. Check for existing documentation - README, ARCHITECTURE.md, ADRs, etc.
3. Create initial journal - Use the template, populated with discovered information
4. Note gaps - Mark areas where context is missing for later filling

## [Section with gaps]

> **Note**: This section needs input from someone with more context on the
> original decisions. Placeholder based on code archaeology.

Updating Guidelines

Keep It Current

• Update immediately when decisions are made, not later
• Remove outdated information rather than letting it accumulate
• Mark uncertain information explicitly

Keep It Useful

• Focus on why, not just what (code already shows what)
• Include enough context that future-you understands
• Link to relevant code/files where helpful

Keep It Honest

• Document mistakes openly—they're learning opportunities
• Note when decisions were made with incomplete information
• Update if circumstances change and past decisions need revision

Example Entries

Decision Entry

### Database Choice: PostgreSQL - 2024-01-15
**Context**: Needed persistent storage for user data and transactions.
**Options Considered**:
1. PostgreSQL: Mature, strong JSON support, familiar
2. MySQL: Also mature, but weaker JSON handling
3. MongoDB: Document model appealing but consistency concerns
**Decision**: PostgreSQL with JSONB for flexible fields
**Rationale**: Strong consistency needed for transactions, JSONB provides
document flexibility where needed, team has experience.
**Consequences**: Need to manage migrations carefully, JSONB queries can
be slower than native columns if overused.

Mistake Entry

### N+1 Query in User Dashboard - 2024-02-03
**What happened**: Dashboard became slow with >100 users. Each user card
triggered a separate query for their recent activity.
**Root cause**: Used ORM's lazy loading without considering list context.
**Impact**: Page load went from 200ms to 8s for large accounts.
**Lesson**: Always check query count when rendering lists of associated data.
**Prevention**: Added query count assertion to dashboard tests. Use
`includes()` for list pages.

Pattern Entry

### Service Objects for Complex Operations
**When to use**: Any operation that involves multiple models or external
services, or has complex business logic.
**Implementation**: Create class in `app/services/`, single public method
`call`, return Result object.
**Example**: `app/services/process_payment.rb`
**Why this way**: Keeps controllers thin, makes testing straightforward,
isolates complexity.

File Template

The starter template is available at assets/journal_template.md. Copy this when initializing a new journal.