DEV Community

Cover image for Escaping the Dumbzone, Part 3: Knowledge Management & Configuration
diggidydale
diggidydale

Posted on

Escaping the Dumbzone, Part 3: Knowledge Management & Configuration

#ai #softwareengineering #development #programming

Part 3 of 4 in the "Escaping the Dumbzone" series

In Part 2, we covered subagents—how to isolate exploration and keep your main context clean.

But here's another problem: you learn something useful during a session, and it stays trapped in that session. Next time you start Claude? Amnesia. You're explaining the same things again.

This part is about making knowledge stick — across sessions, across tasks, across your whole team.

The Crystallisation Problem

Every session, you discover things:

  • "Oh, the auth module is in an unexpected place"
  • "Tests need this specific env var set"
  • "Don't touch that legacy file, it breaks everything"

These insights cost you context to discover. Then the session ends. Gone.

Next session, you (or Claude) rediscover them. Burning context again. It's like Groundhog Day but with tokens.

The fix is crystallisation — taking ephemeral learnings and storing them somewhere durable.

Knowledge crystallisation

What to Call These Learnings?

You might call them "thoughts," but there are better names:

Name Vibe
Insights Wisdom extracted from exploration
Learnings Knowledge gained through work
Memory Crystals Compressed, durable knowledge structures
Distillations Essence from verbose exploration

I'd go with "Insights" or "Learnings" — clear, unpretentious, and they convey that this is extracted knowledge, not raw data.

The Memory Bank Pattern

Cline popularised a structured approach with dedicated files:

memory-bank/
├── projectbrief.md      # What is this project?
├── productContext.md    # Business/user perspective
├── systemPatterns.md    # Architecture decisions
├── techContext.md       # Dev environment & stack
├── activeContext.md     # Current focus area
└── progress.md          # Status tracking
Enter fullscreen mode Exit fullscreen mode

Memory Bank Structure

The workflow is dead simple:

  1. Start session → Read memory bank files
  2. Do work → Context accumulates as normal
  3. End session → Update relevant memory bank files

Your AI starts each session with project knowledge instead of a blank slate. The upfront token cost is small (a few hundred tokens) compared to re-discovering everything.

CLAUDE.md: Your Project's Brain

Claude Code has a built-in mechanism for this: CLAUDE.md. It's read automatically at session start and treated as high-priority instructions.

Basic Example 

# Project: E-Commerce Platform

## Stack
- Next.js 14 with App Router
- PostgreSQL via Prisma
- Redis for sessions

## Commands
- `npm run dev` — Dev server (port 3000)
- `npm test` — Jest tests
- `npm run db:migrate` — Run Prisma migrations

## Gotchas
- Auth uses localStorage fallback for Safari (ITP issues)
- Don't modify /legacy — it's load-bearing spaghetti
- Tests require DATABASE_URL env var

## Current Focus
Migrating from JWT to session-based auth.
Enter fullscreen mode Exit fullscreen mode

Why This Works

Here's the key insight from HumanLayer:

"Claude will ignore the contents of your CLAUDE.md if it decides that it is not relevant to its current task."

This sounds bad but it's actually good. Anthropic intentionally made Claude deprioritise irrelevant instructions. It means you can include project-wide context without bloating every single task.

But it also means: make your CLAUDE.md universally relevant, not stuffed with edge cases.

The 150-200 Rule

HumanLayer's research uncovered a crucial constraint: LLMs can reliably follow about 150-200 instructions.

Claude Code's built-in system prompt already uses ~50 of those. That leaves you with maybe 100-150 before reliability drops.

Keep CLAUDE.md under 300 lines. HumanLayer's is under 60.

Quality over quantity. Every line should earn its place.

CLAUDE.md Anti-Patterns

Don't Use Claude as a Linter

This is tempting but wrong:

## Code Style (DON'T DO THIS)
- Use 2-space indentation
- Maximum line length 80 characters
- Always use semicolons
- Prefer const over let
- Use arrow functions for callbacks
- ... (50 more rules)
Enter fullscreen mode Exit fullscreen mode

This bloats your context and degrades performance. Claude isn't a linter. It's an AI.

"Never send an LLM to do a linter's job."

Use actual linters (Biome, ESLint) and run them through Claude Code hooks. The linter enforces style; Claude focuses on logic.

Don't Auto-Generate

It's tempting to run /init and call it done. Don't.

"CLAUDE.md is one of the highest leverage points of the harness."

Manually craft every line. You know your project better than any auto-generator. The few minutes spent writing a good CLAUDE.md pays dividends across hundreds of sessions.

Don't List Every Possible Command 

## Commands (DON'T DO THIS)
- npm run dev
- npm run build
- npm run test
- npm run test:watch
- npm run test:coverage
- npm run lint
- npm run lint:fix
- npm run format
- npm run typecheck
- ... (20 more)
Enter fullscreen mode Exit fullscreen mode

Claude doesn't need a reference manual. It can read package.json. Include the non-obvious stuff, skip the obvious.

Progressive Disclosure

Instead of cramming everything into CLAUDE.md, use separate files loaded on demand:

docs/
├── building.md         # How to build & deploy
├── architecture.md     # System design
├── conventions.md      # Code patterns we use
└── testing.md          # Test strategy & setup
Enter fullscreen mode Exit fullscreen mode

Then in CLAUDE.md:

## Documentation
- Read `docs/architecture.md` when working on system design
- Read `docs/testing.md` before writing tests
- Read `docs/conventions.md` for code review
Enter fullscreen mode Exit fullscreen mode

Progressive Disclosure

Context is loaded when needed, not upfront. Your baseline stays lean.

Session Hygiene

Even with great knowledge management, sessions get bloated. Here's how to stay clean.

The /compact Command

When context is getting full, /compact compresses your conversation. It keeps important stuff, drops the noise.

Timing matters: Compact at 70%, not 90%.

Why? You need room to finish your current task. If you compact at 90% and the task needs another 15% of context, you're stuck.

compaction-timing

The /clear Command

Switching tasks? Use /clear to reset context within your session.

Less disruptive than starting a new session. Good for "I'm done with feature X, now working on feature Y."

Just Start Fresh

Real talk: if you've been debugging something for an hour and want to switch to documentation, open a new chat.

It feels wasteful. It's not. Each fresh session:

  • Zero context rot
  • No "lost in the middle" issues
  • No cross-contamination from unrelated tasks

The best context management is sometimes no context at all.

Iterative Refinement

Your CLAUDE.md should evolve. Here's the loop:

  1. Add an instruction
  2. Give Claude a task that relies on it
  3. Watch what happens
  4. Refine if it didn't work
  5. Commit so teammates benefit

Claude Code has a shortcut: press # during a session to add instructions that get incorporated into CLAUDE.md automatically. Use it when you discover something worth remembering.

Hierarchical Summarisation

As sessions progress, use layered approaches:

Age Treatment
Last 10-15 messages Keep verbatim
Earlier in session Compress to summaries
Stable project facts Move to CLAUDE.md
One-time learnings Memory bank files

Research suggests: prefer raw > compaction > summarisation. Each step loses fidelity. Only summarise when you must.

Key Takeaways

  1. Crystallise learnings — Don't rediscover the same things every session
  2. Memory bank files — Structured project knowledge that persists
  3. CLAUDE.md is high-leverage — Keep it under 300 lines, manually crafted
  4. Don't use Claude as a linter — Real linters via hooks, Claude for logic
  5. Progressive disclosure — Load detailed context only when needed
  6. Session hygiene — Compact at 70%, clear between tasks, start fresh when needed
  7. Iterate your config — CLAUDE.md should evolve with your project

What's Next

We've covered staying out of the Dumbzone (subagents) and making knowledge persist (crystallisation, CLAUDE.md).

But keep an eye out for part 4 where we will cover the more advanced patterns for serious context engineering.

Backpressure control, the Ralph Loop for long-running autonomous tasks, and the 12 Factor Agents framework.

Further Reading

Top comments (0)