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

```typescript
// ✅ 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

```typescript
// ✅ 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

```markdown
[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

```markdown
#### 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:**

```typescript
// ❌ 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