CLAUDE.md: Project Memory That Makes AI Understand Your Context

There’s one near-universal frustration among developers who start using Claude Code: every new session, you have to re-explain the project architecture, the technical stack, the established conventions, and the team-agreed rules. Five minutes of explanation before you can start working. Every single day.

CLAUDE.md is the solution. This file is the “project memory” that Claude Code automatically reads in every session — so the AI always has the right CLAUDE.md golang claude code context without needing to be re-briefed. In this article we build one that works for a production Golang project.

04.1 What Is CLAUDE.md and How It Works

CLAUDE.md is a Markdown file placed at the project root. Claude Code reads it automatically at the start of every session, which turns it into persistent project context. The flow below contrasts a workflow without the file against one with it, so the payoff is concrete before we look at structure.

1Without CLAUDE.md:
2Session 1: [Explain architecture 5 min] → [Coding 30 min]
3Session 2: [Explain architecture 5 min again] → [Coding 30 min]
4Session N: [Explain architecture 5 min again] → [Coding 30 min]
5
6With CLAUDE.md:
7Session 1: [Claude reads CLAUDE.md automatically] → [Coding immediately]
8Session 2: [Claude reads CLAUDE.md automatically] → [Coding immediately]
9Session N: [Claude reads CLAUDE.md automatically] → [Coding immediately]

The takeaway: the value is not only saved minutes. CLAUDE.md also ensures Claude Code generates code consistent with the agreed architecture, even when the person driving it is a new developer who hasn’t memorized the conventions yet.

04.2 Six Mandatory Components for Go Projects

Based on running SDD in production Golang projects, six components should always be present:

Component 1: Project Overview — what this service is and what it does.

Component 2: Tech Stack with Specific Versions — exact library names and versions pulled from go.mod.

Component 3: Architecture Rules — explicit layer-dependency rules written in MUST / MUST NOT language.

Component 4: Naming Conventions — for files, types, packages, and errors.

Component 5: Spec Rules — instruct Claude to always require a spec before implementing.

Component 6: Reference Code Patterns — point to existing files that demonstrate the established patterns.

04.3 Complete CLAUDE.md for Santekno Shop

Instead of describing each component in the abstract, here is the complete CLAUDE.md we use throughout this series — a real, copy-ready starting point for the Order Service.

 1# CLAUDE.md — Santekno Shop
 2
 3## Tech Stack
 4Language: Go 1.22+, HTTP: Echo v4, DB: pgx/v5
 5Cache: go-redis/v9, Messaging: confluent-kafka-go v2
 6Auth: golang-jwt/jwt/v5, UUID: github.com/google/uuid
 7Testing: testify/suite + gomock, Logging: log/slog (stdlib)
 8
 9## Architecture Rules
10Layer order: domain → usecase → repository → delivery/http
11
12MUST NOT:
13- Direct DB call from handler or usecase
14- Import delivery package from other layers
15- Business logic in handler layer
16
17MUST:
18- Dependency injection via constructor
19- Interface for all external dependencies
20- Error wrapping: fmt.Errorf("context: %w", err)
21- Context propagation in all function signatures
22- Structured logging: slog.InfoContext(ctx, ...)
23
24## Domain Types
25IDs: always uuid.UUID from github.com/google/uuid
26Prices: always int64 in cents (PriceCents, TotalAmountCents)
27NEVER use float64 for prices
28
29## Spec Rules
30Every new feature MUST have a spec BEFORE implementation.
31If asked to implement without a spec:
32"Let's create the spec at specs/domain/[feature].md first, then implement."
33Template: specs/_templates/feature-spec.md
34
35## Reference Patterns
36Handler: internal/delivery/http/handler/order_handler.go
37Usecase: internal/usecase/order/create_order.go
38Repository: internal/repository/postgres/order_repository.go
39Test: internal/usecase/order/create_order_test.go

What to notice: the file is compact, imperative, and every rule is verifiable. It tells Claude the “how” (architecture, conventions) and the “with what” (stack, versions) in fewer than 40 lines — small enough to stay in context, specific enough to steer real code.

04.4 How Claude Code Uses CLAUDE.md

When claude launches at the project root, it reads CLAUDE.md automatically and applies it to every reply. The two blocks below show the difference the file makes for the same prompt — first without it, then with it.

1> Create a function to create an order
2
3[Claude might use float64 for price, or query DB directly from handler]

That first result ignores your conventions because nothing told it about them. Add CLAUDE.md to the project root and the very same prompt now produces the compliant output below.

1> Create a function to create an order
2
3[Claude automatically uses uuid.UUID for IDs, int64 for prices,
4 asks about the spec, and follows the clean architecture layers]

The takeaway is stark: the same one-line prompt produces architecture-compliant code only when CLAUDE.md is present. Without it, the AI falls back to generic defaults that violate your conventions.

04.5 Validating CLAUDE.md Effectiveness

How do you know CLAUDE.md is actually working? Run a small set of “probe prompts” and check the responses against the expectations noted inline.

 1# Probe 1: Architecture compliance
 2"Write a handler that directly queries the database for order creation"
 3# Expected: Claude refuses and explains layer separation
 4
 5# Probe 2: Spec awareness
 6"Implement a refund order feature"
 7# Expected: Claude asks for the spec before implementing
 8
 9# Probe 3: Price convention
10"Create a field for product price"
11# Expected: Claude uses int64 named PriceCents
12
13# Probe 4: Error handling
14"How should I handle an 'order not found' error?"
15# Expected: Claude mentions ErrOrderNotFound as a sentinel error

If every probe returns the expected behavior, CLAUDE.md is doing its job. If any probe drifts, the corresponding section of the file is either missing, too vague, or contradicted somewhere else.

04.6 CLAUDE.md for Team Collaboration

CLAUDE.md is not a personal document — it is a team document that must be maintained collaboratively:

• All team members can propose changes.
• Merges to main require review by a tech lead or senior engineer.
• Update it whenever a new library is decided, a new pattern is agreed, or a new architectural decision is made.

CLAUDE.md is the “technical constitution” of the project — it defines how AI tools behave in your codebase.

04.7 Security Considerations

CLAUDE.md is sent to Anthropic’s API as part of every request, so its contents leave your machine — treat it accordingly. The contrast below shows the one mistake that must never happen versus the safe alternative.

1# NEVER put this in CLAUDE.md
2DATABASE_URL=postgres://admin:password123@prod-db:5432/shop
3
4# CORRECT: reference environment variable names, not values
5Database config is in the environment variable: DATABASE_URL
6Format: postgres://user:pass@host:port/dbname

The rule to carry away: never include API keys, secrets, credentials, connection strings with passwords, real user data, or production IP addresses. Reference the environment variable name, never its value.

04.8 CLAUDE.md vs README.md

A common confusion is whether CLAUDE.md replaces README.md. It does not — they serve different readers, as the table below makes clear.

The takeaway: both are needed and complementary. README.md is for a human seeing the project for the first time; CLAUDE.md is for the AI working in the project every day.

04.9 Anti-Patterns to Avoid

A few CLAUDE.md patterns consistently fail in practice, and the second one is worth seeing directly.

Anti-pattern 1: Too long (>500 lines) — consumes too much of the context window, causes Claude to “focus” on some parts and ignore others. Target 150–300 lines.

Anti-pattern 2: Too generic — the contrast below shows why generic rules are useless.

1BAD:  "Use best practices"
2GOOD: "Use pgx/v5 (not database/sql) — see ADR-001 for reasoning"

The lesson: a rule Claude can act on names a concrete choice and, ideally, the reason for it. “Best practices” is not actionable.

Anti-pattern 3: Contradictory rules — rules that conflict with each other confuse Claude.

Anti-pattern 4: No code examples — rules without examples are misinterpreted more often. Include a snippet for every critical rule.

04.10 Building CLAUDE.md for an Existing Project

If your project is already running and has no CLAUDE.md, don’t write it from memory — extract it from the code you already have. The four-step recipe below produces an accurate draft fast.

 1Step 1: Extract from existing code
 2Prompt Claude Code:
 3"Analyze this codebase and create a CLAUDE.md draft that summarizes:
 4 1. Tech stack used (with versions from go.mod)
 5 2. Architecture patterns used
 6 3. Naming conventions consistent in existing code
 7 4. Error handling patterns
 8 5. Testing approach"
 9
10Step 2: Review and correct
11Review the generated draft. Add rules that weren't captured.
12Correct wrong assumptions.
13
14Step 3: Add spec rules
15Add the section about the spec and SDD workflow.
16
17Step 4: Team review
18Share with the team, collect feedback, finalize.

The takeaway: let the AI do the first-pass archaeology, but you own steps 2–4. The extracted draft is a starting point, not a source of truth until a human has validated it.

04.11 CLAUDE.md as Onboarding Document

Unexpected bonus: a well-written CLAUDE.md doubles as an excellent onboarding document for new developers.

A new developer can read CLAUDE.md to:

• Understand the project architecture in 10 minutes
• Know which conventions to follow
• Know where to find reference code
• Understand the spec process

This stays more up-to-date than Confluence onboarding docs, because if the code changes but CLAUDE.md doesn’t, the AI generates wrong code — which creates a real incentive to keep it accurate.

04.12 CLAUDE.md Integration with the Spec Workflow

CLAUDE.md and spec files are not competitors — they cover different questions and combine into complete context. The mapping below shows the division of labor.

1CLAUDE.md: "How" → Architecture rules, conventions, patterns
2           "With what" → Tech stack, libraries, versions
3
4specs/domain/cancel-order.md:
5           "What" → User story, AC, EC, NFR
6           "Why" → Business context

When Claude Code has access to both, the result is powerful: code that follows the architecture and the specification at the same time.

04.13 CLAUDE.md for Microservice Environments

With multiple services there are three viable strategies:

Strategy 1: One CLAUDE.md per service — specific and focused, but with some duplication.

Strategy 2: Shared base + service override — reference a common base file for shared conventions.

Strategy 3: Monorepo hierarchy — shared conventions at the root, service-specific additions in each service directory.

For Santekno Shop we use Strategy 1, since we’re a monorepo at an early stage.

04.14 Versioning CLAUDE.md

CLAUDE.md lives in git, so it is versioned automatically — but a small header changelog makes intent-level history readable at a glance, as shown below.

1# CLAUDE.md
2# Last major update: 2025-07-01 (Add Redis caching rules)
3
4## Changelog
5| Date | Change |
6|------|--------|
7| 2025-07-01 | Add Redis caching convention |
8| 2025-06-01 | Add Kafka event pattern |
9| 2025-05-01 | Initial |

The takeaway: pair git history with an in-file changelog and a sprint-planning review — at least monthly, ask what needs to be added, changed, or removed.

04.15 CLAUDE.md with Richer Context

Beyond rules and conventions, CLAUDE.md can hold domain knowledge. A glossary removes ambiguity about business terms, as in the block below.

1## Domain Glossary
2- **Order:** Purchase transaction created by a customer. One order can have multiple items.
3- **Cart:** Collection of items not yet checked out. A cart can be modified, an order cannot.
4- **SKU:** Unique code for each product variant.
5- **Merchant:** Seller who lists products on the platform.

That glossary means Claude never has to guess what “cart” versus “order” implies in your domain. Frequently asked architectural questions deserve the same treatment, captured directly in the file:

1## Architecture FAQ
2**Q: Why not use GORM?**
3A: ADR-001 decision. pgx/v5 chosen for better performance and explicit query control.
4
5**Q: Why event-driven for notifications?**
6A: Decoupling between Order Service and Notification Service. Details in ADR-005.

The lesson: an embedded FAQ pre-answers the “why” questions Claude (and new hires) would otherwise raise, so decisions don’t get relitigated in every session.

04.16 CLAUDE.md for Context Window Management

CLAUDE.md is loaded into Claude’s context window on every session, so every line spends budget. Optimize it:

• Keep it under 300 lines — each line uses precious context.
• Put the most-used information first (architecture rules, naming conventions).
• Remove outdated rules promptly — stale rules waste tokens and confuse Claude.
• Use concise language — bullet points over paragraphs for rules.

04.17 Common Mistakes When Creating CLAUDE.md

Mistake 1: Writing CLAUDE.md at the end of the project — it’s most effective when written at the start and updated incrementally.

Mistake 2: Not explaining “why” for non-obvious rules — context helps Claude respect the constraint, not just follow it mechanically.

Mistake 3: Treating CLAUDE.md as onboarding-only — it’s for daily AI work, not just for new hires.

Mistake 4: Not updating it when the architecture changes — an outdated CLAUDE.md can be more harmful than none at all.

04.18 Tips & Gotchas

Tip 1: Start from a template, not a blank file — 70% correct beats nothing.

Tip 2: Use imperative language — “MUST” and “MUST NOT” are more effective than “should” or “it’s better if.”

Tip 3: Include code examples for important patterns — critical rules deserve at least one snippet.

Tip 4: Review it monthly — schedule it into sprint planning.

Gotcha 1: CLAUDE.md consumes the context window — the longer it is, the less room for conversation and code.

Gotcha 2: Claude Code doesn’t always follow CLAUDE.md 100% — especially for long, complex rules. Always review output.

Gotcha 3: Update CLAUDE.md alongside architecture changes — an outdated file is worse than no file.

Gotcha 4: One CLAUDE.md per project/service — don’t mix multiple projects’ rules in one file.

04.19 Summary

CLAUDE.md is the foundation of an efficient SDD workflow. Without it, every Claude Code session starts from zero — risking code that is inconsistent with your project architecture.

Six mandatory components: project overview, tech stack with specific versions, explicit architecture rules, naming conventions, spec rules, and reference code patterns.

An effective CLAUDE.md is compact (150–300 lines), holds imperative rules with code examples, and is updated alongside architecture changes.

Never put credentials in CLAUDE.md — it is sent to the Anthropic API. Reference environment variable names, not values.

CLAUDE.md works alongside spec files — it is not a replacement. CLAUDE.md holds the “how” and “with what”; spec files hold the “what” and “why.”

In the next article we enter Part 2 of this series: a deep dive into the anatomy of a good specification — user stories, acceptance criteria, and edge cases that can genuinely serve as a source of truth.