Learn by Directing AI
All materials

project-memory-template.md

Project Memory: How to Write CLAUDE.md and AGENTS.md

What project memory is

Project memory is a file that loads at the start of every AI session. It gives AI persistent context about your project -- the data dictionary, naming conventions, known quality issues, design decisions. Without it, every session starts from zero and AI has to rediscover (or invent) everything you've already decided.

Two files, two formats, one purpose: keep AI on the rails.

CLAUDE.md format

CLAUDE.md is the project memory file for Claude Code. It loads automatically when Claude starts in your project directory. It supports tool-specific features: ancestor file hierarchy (a parent CLAUDE.md at ~/dev/ applies to all projects), auto-memory (Claude can append notes), and path-scoped rules.

Sections

# [Project Name] -- [Brief Description]

## Project
[Who is the client. What are you building. One paragraph.]

## Tech stack
[Languages, frameworks, databases, tools. Bulleted list.]

## Data dictionary
[Source tables and their fields. What each field means. Type and range.]

## Known quality issues
[Things that will trip up AI if it doesn't know about them.
Be specific: "corrections arrive as complete day re-exports" not "data has quality issues."]

## dbt naming conventions
[stg_, int_, fct_, dim_ prefixes. What each layer does. What belongs where.]

## Work breakdown
[Current ticket list or task structure. What's done, what's next.]

## Verification targets
[What "correct" looks like. Row counts, test expectations, acceptance criteria.]

## Commit convention
[When to commit. What messages look like.]

AGENTS.md format

AGENTS.md is the cross-platform standard. Any AI coding agent that supports the convention reads this file. It captures the same constraints as CLAUDE.md but in a format that transfers.

Sections

Same sections as CLAUDE.md. The content is the same essential information, written so any agent can follow it -- no Claude-specific features (no path-scoped rules, no auto-memory references).

Writing both is not duplication. CLAUDE.md uses tool-specific capabilities that make Claude more effective. AGENTS.md ensures that if you switch tools or a teammate uses a different agent, the project constraints still apply.

Good vs bad entries

Bad (vague)

## dbt naming conventions
Follow dbt best practices for naming.

## Known quality issues
Data may have some quality issues.

AI interprets "best practices" using its training data defaults. Different sessions may produce different interpretations. "Some quality issues" tells AI nothing actionable.

Good (specific, testable)

## dbt naming conventions
- Staging models: stg_[source]_[table] (e.g., stg_mill1_daily)
- Source-conform only in staging: no joins, no business logic, cast types and rename columns
- Intermediate models: int_[description] (e.g., int_daily_operations)
- Fact models: fct_[description] -- aggregated business metrics
- Dimension models: dim_[entity] -- entity tracking over time

## Known quality issues
- Mill 1 corrections: supervisor re-exports the entire day's file when correcting an error. The corrected file contains all records for that day, both correct and corrected, with no flag. Use MERGE on natural key to avoid duplicates.
- Mill 2 advance payments: records where weight_kg and harvest_quality are null represent advance payments to farmers. These are normal business operations, not data errors. Do not filter them out -- they are needed for farmer payment tracking.
- Grade mapping: Mill 1 uses text (premium/standard/low), Mill 2 uses letter codes (A/B/C). Map explicitly: A=premium, B=standard, C=low. Do not rely on AI to infer the mapping.

Every entry is a specific instruction that AI can follow and you can verify.

When to update project memory

  • After each design decision: You chose MERGE keys, decided full vs incremental per source, set the grain. Add it.
  • After discovering a quality issue: You found that Mill 2 advance payments have null weight. Add it before it trips up the next session.
  • After establishing a convention: You decided all staging models are source-conform with no joins. Add it so AI follows it consistently.
  • After adding infrastructure: You set up pre-commit hooks or watermark monitoring. Add what exists and what it catches.
  • At the end of each work session: Review what you decided or discovered. If it's not in the file, add it.

The file grows as the project grows. A project memory file from the end of a project should be substantially richer than the one at the start.