[FEATURE] Case Study: Governing stateless sessions at scale with CLAUDE.md + MEMORY.md

Governing AI Sessions at Scale: How CLAUDE.md + MEMORY.md Enabled a 171K-Line Production System

When you scale Claude Code beyond prototyping — 171K lines, 96 DB tables, multiple parallel sessions over months — session statelessness becomes the primary failure mode. This post describes a 3-layer governance pattern (CLAUDE.md + MEMORY.md + parallel coordination) that solved it.

The Problem: Stateless Sessions × Parallel Execution = Chaos

Claude Code sessions start fresh. No memory of past bugs, no awareness of dangerous files, no knowledge of architectural decisions. For prototypes this is fine. For a production system built across months with multiple parallel sessions, it's the #1 failure source:

• Session A reintroduces a bug Session B fixed last week
• Session C refactors a file Session D depends on
• Every session rediscovers the same pitfalls independently

I needed governance — not for the code, but for the AI itself.

The Solution: 3-Layer Governance

Layer 1: CLAUDE.md — Incident-Driven Constitution

Every rule traces back to an actual production failure. This is not a style guide.

### 1. One Table, One Gateway
- crawler_raw_listings → only through crawlerRawListingRepo.js
- No direct prisma.[table].create/update in service code

### 2. Don't Do the Same Thing Twice
- Check existing code before implementing. Extend, don't create.

### 3. New Abstractions Only After Proof
- No new Service/Manager/Orchestrator unless same code repeats in 3+ places

### 4. Same Bug Twice → Structural Fix
- Second occurrence = fix the structure, not the symptom
- Record pattern in MEMORY.md

### 5. Deletion First
- Removing 100 lines of dead code > Adding 100 lines of new code

### 6. Pre-deployment: grep all callers of modified functions

### 7. Priority: Safety > Scope > Quality > Speed

The AI must also clear a 6-question pre-deployment checklist before any change — including "Has this area been reverted before?" which forces git history checks on hot files.

CTO obligations: the AI must report before creating new files, modifying 4+ files, changing DB schema, or connecting anything to automation.

Layer 2: MEMORY.md — Persistent Cross-Session State

Persistent memory that carries operational knowledge across sessions:

Bug Pattern Registry (16 tracked):

| ID  | Pattern                 | Rule                                      | Status |
|-----|-------------------------|--------------------------------------------|--------|
| 002 | Price unit won↔man-won  | Parser=won → normalize÷10000 → DB=man-won  | Watch  |
| 003 | UTC/KST mismatch        | Always toLocaleString + Asia/Seoul          | Watch  |
| 014 | Year parsing cascade    | NEVER fallback to getFullYear()             | Fixed  |

Hot File List:

| File                        | Risk    | Reason                                |
|-----------------------------|---------|---------------------------------------|
| TwoStageCrawlerPipeline.js  | EXTREME | BUG-014: year fallback → 4-layer data corruption |
| CrawlerExecutionService.js  | EXTREME | BUG-012: 6 repeat failures            |
| PeriodContentService.js     | HIGH    | 3,430 lines, 15+ modifications        |

Temporary Change Ledger: tracks what was changed temporarily, when to revert, and what breaks if forgotten.

Each new session reads MEMORY.md on startup, inheriting accumulated operational context.

Layer 3: Parallel Session Coordination

Multiple Claude Code sessions run simultaneously with shared governance:

• CLAUDE.md = shared rules → consistent decisions across sessions
• MEMORY.md = shared state → no session touches a hot file unknowingly
• Single branch = no merge conflicts between parallel sessions

This turns independent AI sessions into a coordinated team.

Production Result

| Metric | Value |
|--------|-------|
| Codebase | 171,000 lines (81K backend + 90K frontend) |
| Database | 96 tables, 252 indexes, 33 migrations |
| API | 517 endpoints, 71 route files |
| Refined data | ~130,000 market records |
| Pricing snapshots | ~85,000 records |
| Users | ~50 active |

The system: multi-source crawler (2-stage pipeline, proxy rotation, stealth engine) → ML pricing (12-segment GBM, 3-tier fallback) → automated reports (weekly/monthly/quarterly, B2B + B2C) → video generation → user notifications. Full pipeline runs automatically in production. Security stack includes RFC 9457 errors, helmet, JWT, rate-limiting, and bot detection.

What the Governance Couldn't Prevent

| Issue | Number | Why governance didn't help |
|-------|--------|---------------------------|
| Git reverts | 50+ | Prevents repeat failures, not first-time mistakes |
| Test coverage | 0.8% | Governance doesn't write tests — biggest gap |
| Monolith files | 5 × 2,000+ lines | Rules prevent new ones, don't refactor existing |
| TODO/FIXME | 106 | Debt accumulates faster than rules can address |

The system is better at preventing the second occurrence than the first. Each new failure becomes a new rule — it's a learning system with a one-failure delay.

Insights

1. CLAUDE.md is incident-driven policy, not a style guide. "Never fallback to getFullYear()" exists because BUG-014 cascaded through 4 pipeline layers. Every rule has a scar behind it.

1. MEMORY.md is the highest-leverage file in the repo. Without it, session #50 is as naive as session #1. With it, accumulated operational knowledge persists.

1. Parallel sessions without shared governance create contradictions. One session adds a feature while another removes the dependency. CLAUDE.md is the coordination protocol.

1. Bug IDs force structural thinking. BUG-003 (UTC/KST) appeared three times. The ID made the pattern visible. The fix was structural (mandatory timezone helper), not another patch.

Context

I have no programming background — I work in the Korean commercial truck industry. All code was generated by Claude Code. The governance system was designed through months of production trial and error.

Open Questions

• Session state persistence: MEMORY.md works but is manual. Has anyone automated governance rule extraction from git history or CI failures?
• Test generation under governance: CLAUDE.md drives architecture but doesn't produce tests. Any patterns for making session governance test-aware?
• Parallel session conflict detection: Beyond shared files, are there mechanisms to detect when two sessions are about to modify overlapping code paths?

---

Developed through production operation, not theoretical design. All numbers from actual codebase analysis.