journaling-codebase-decisions

To document architecture decisions, you maintain a living `.claude/journal.md` file in the repository root. It captures the context, tradeoffs, and rationale behind tech stack choices to preserve institutional memory for future reference.

Development teams repeat engineering mistakes because codebases only capture what was built, not the reasoning behind choices. Documenting anti-patterns and lessons learned in a centralized journal prevents repeated errors during onboarding.

The best way to speed up engineering onboarding is generating an initial journal from existing code and documentation. This provides new team members with immediate context regarding established patterns and architecture decisions.

You create standardized pattern documentation using pre-built markdown templates for consistent entry formatting. These templates structure decisions, established patterns, and mistakes within a centralized codebase journal file.

Yes, you can use structured templates to track technical debt and lessons learned. The skill provides pre-built markdown templates that standardize the formatting of mistakes, anti-patterns, and retrospective lesson capture.

You need to update the codebase journal after finalizing key tech stack choices or migrations. The skill provides specific update triggers to maintain documentation when architecture decisions or established patterns change.