CLAUDE.md Learning Integration

Use this skill to identify learning opportunities and document insights into CLAUDE.md. The goal is to ensure hard-won knowledge is preserved for future developers.

When to Use

• User discovers a gotcha or unexpected behavior

• User completes a complex feature and wants to document learnings

• User makes an architectural decision worth preserving

• User fixes a tricky bug with insights to share

• User says "I wish I'd known this earlier"

Philosophy

Core Principle: Knowledge that isn't documented is knowledge that will be lost. Every hard-won insight must be preserved for future developers.

Identifying Learning Opportunities

Watch for these signals during development:

• Gotchas or unexpected behavior discovered

• "Aha!" moments or breakthroughs

• Architectural decisions being made

• Patterns that worked particularly well

• Anti-patterns encountered

• Tooling or setup knowledge gained

Discovery Questions

About the Problem

• What was unclear or surprising at the start?

• What took longer to figure out than expected?

• What assumptions were wrong?

• What would have saved time if known upfront?

About the Solution

• What patterns or approaches worked particularly well?

• What patterns should be avoided?

• What gotchas or edge cases were discovered?

• What dependencies or relationships were not obvious?

About the Context

• What domain knowledge is now clearer?

• What architectural decisions became apparent?

• What testing strategies were effective?

• What tooling or setup was required?

Learning Significance Assessment

Document if ANY of these are true:

• Would save future developers significant time (>30 minutes)

• Prevents a class of bugs or errors

• Reveals non-obvious behavior or constraints

• Captures architectural rationale or trade-offs

• Documents domain-specific knowledge

• Identifies effective patterns or anti-patterns

• Clarifies tool setup or configuration gotchas

Skip if ALL of these are true:

• Already well-documented in CLAUDE.md

• Obvious or standard practice

• Trivial change (typos, formatting)

• Implementation detail unlikely to recur

CLAUDE.md Section Classification

Determine which section the learning belongs to:

Existing Sections

• Core Philosophy - Fundamental principles (TDD, FP, immutability)

• Testing Principles - Test strategy and patterns

• TypeScript Guidelines - Type system usage

• Code Style - Functional patterns, naming, structure

• Development Workflow - TDD process, refactoring, commits

• Working with Claude - Expectations and communication

• Example Patterns - Concrete code examples

• Common Patterns to Avoid - Anti-patterns

New Sections (if learning doesn't fit existing)

• Project-specific setup instructions

• Domain-specific knowledge

• Architectural decisions

• Tool-specific configurations

• Performance considerations

• Security patterns

Formatting Guidelines

For Principles/Guidelines

New Principle Name

Brief explanation of why this matters.

Key points:

• Specific guideline with clear rationale
• Another guideline with example
• Edge case or gotcha to watch for

// ✅ GOOD - Example following the principle
const example = "demonstrating correct approach";

// ❌ BAD - Example showing what not to do
const bad = "demonstrating wrong approach";

For Gotchas/Edge Cases

Gotcha: Descriptive Title

Context: When does this occur Issue: What goes wrong Solution: How to handle it

// ✅ CORRECT - Solution example
const correct = handleEdgeCase();

// ❌ WRONG - What causes the problem
const wrong = naiveApproach();

For Project-Specific Knowledge

Project Setup / Architecture / Domain Knowledge

Specific Area

Clear explanation with:

• Why this is important
• How it affects development
• Examples where relevant

Documentation Proposal Format

CLAUDE.md Learning Integration

Summary

Brief description of what was learned and why it matters.

Proposed Location

Section: [Section Name] Position: [Before/After existing content, or new section]

Proposed Addition

[Exact markdown content to add to CLAUDE.md]

Rationale

• Why this learning is valuable
• How it fits with existing guidelines
• What problems it helps prevent
• Time saved by documenting this

Verification Checklist

• Learning is not already documented
• Fits naturally into CLAUDE.md structure
• Maintains consistent voice and style
• Includes concrete examples if applicable
• Prevents future confusion or wasted time

Voice and Style

• Imperative tone: "Use X", "Avoid Y", "Always Z"

• Clear rationale: Explain WHY, not just WHAT

• Concrete examples: Show good and bad patterns

• Emphasis markers: Use bold for critical points, ❌ ✅ for anti-patterns

• Structured format: Use headings, bullet points, code blocks consistently

Quality Standards

• Actionable: Reader should know exactly what to do

• Specific: Avoid vague guidelines

• Justified: Explain the reasoning and consequences

• Discoverable: Use clear headings and keywords

• Consistent: Match existing CLAUDE.md conventions

Quality Gates

Before proposing documentation, verify:

• Learning is significant and valuable

• Not already documented in CLAUDE.md

• Includes concrete examples (good and bad)

• Explains WHY, not just WHAT

• Matches CLAUDE.md voice and style

• Properly categorized in appropriate section

• Actionable (reader knows exactly what to do)

Example Learning Integration

CLAUDE.md Learning Integration

Summary

Discovered that Zod schemas must be exported from a shared location for test files to import them, preventing schema duplication in tests.

Proposed Location

Section: Schema-First Development with Zod Position: Add new subsection "Schema Exports and Imports"

Proposed Addition

#### Schema Organization for Tests

**CRITICAL**: All schemas must be exported from a shared module that both production and test code can import.

```typescript
// ✅ CORRECT - Shared schema module
// src/schemas/payment.schema.ts
export const PaymentSchema = z.object({
  amount: z.number().positive(),
  currency: z.string().length(3),
});
export type Payment = z.infer<typeof PaymentSchema>;

// src/services/payment.service.ts
import { PaymentSchema, type Payment } from "../schemas/payment.schema";

// src/services/payment.service.test.ts
import { PaymentSchema, type Payment } from "../schemas/payment.schema";

Why this matters:

• Tests must use the exact same schemas as production code
• Prevents schema drift between tests and production
• Ensures test data factories validate against real schemas
• Changes to schemas automatically propagate to tests

Common mistake:

// ❌ WRONG - Redefining schema in test file
// payment.service.test.ts
const PaymentSchema = z.object({
  /* duplicate definition */
});

### Rationale

- Encountered this when tests were failing due to schema mismatch
- Would have saved 30 minutes if schema export pattern was documented
- Prevents future schema duplication violations
- Directly relates to existing "Schema Usage in Tests" section

### Verification Checklist

- [x] Learning is not already documented
- [x] Fits naturally into Schema-First Development section
- [x] Maintains consistent voice with CLAUDE.md
- [x] Includes concrete examples showing right and wrong approaches
- [x] Prevents the specific confusion encountered during this task