chronicle

Chronicle — Bootstrap Conventions From Your Codebase

Overview

Interactive command that walks through your codebase and extracts the implicit conventions into explicit, AI-readable rules. Produces a ## Reference Files section and a ## Review Conventions section for your CLAUDE.md.

This is a one-time setup command. After running it, conventions are maintained incrementally through PR feedback capture.

Process

Step 1: Understand the Codebase Shape

Ask the user:

1. "What kind of codebase is this?" (monorepo, single service, library, etc.)
2. "What areas do you work in most often?"
3. "Who are your primary code reviewers?"

Then explore the directory structure. Identify:

• Where source code lives
• How it's organized (by feature, by layer, by domain)
• What test patterns exist
• Config files that enforce standards (linters, formatters, CI checks)

Step 2: Find Reference Files

For each area the user works in, ask:

"Point me to 1-2 files in [area] that you know passed review cleanly — files your reviewer would consider 'the right way to do it.' If you're not sure, point me to the most recently merged PR in this area and I'll look at what was approved."

If the user can't identify reference files, help them:

• Look at recent merged PRs: git log --oneline --merges -20
• Find files with few review iterations
• Ask: "Which files does your reviewer point to when they say 'do it like X'?"

For each reference file identified, record:

### [Category]: [file path]
- Approved by: [reviewer, if known]
- Good example of: [what pattern this demonstrates]
- Last updated: [date of last significant change]

Step 3: Extract Conventions by Comparison

Read 3-5 reference files across different areas. For each one, extract observable patterns in these categories:

Structure & Organization

• File layout (imports, types, constants, logic, exports)
• Naming conventions (files, functions, variables, types)
• Module/package organization

Architecture & Patterns

• How dependencies are accessed (DI, imports, singletons, context)
• Error handling (custom types, propagation style, recovery)
• Data flow (layers, where validation happens, where transformations happen)
• What abstractions are used (and which are NOT — equally important)