Agents Project Memory

Project Memory for Claude Code + Codex (Jan 2026)

Configure project memory so Claude Code and Codex get stable, scoped instructions across sessions while keeping token cost low. Use a single source of truth: keep AGENTS.md as primary and symlink CLAUDE.md to it.

Quick Reference

How Loading Works (High Level)

Claude Code (CLAUDE.md symlink):

• Recursive loading: from the current working directory up to (but not including) filesystem root (/).
• On-demand loading: nested CLAUDE.md files under the cwd are loaded only when Claude reads files in those subtrees.
• Imports: @path/to/file pulls in additional context (max depth: 5; ~ supported).

Codex (AGENTS.md primary):

• Reads AGENTS.md in the repo root or working directory.
• Keep it concise; mirror the same content as CLAUDE.md when supporting both tools.

Workflow (Best Practice)

1. Start with a minimal primary memory file (AGENTS.md, 50–120 lines): what the project is, how it's shaped, and the "must not break" rules. 2. Move long or fragile guidance into .claude/rules/ (one topic per file). 3. Use @imports as navigation for detailed docs instead of copying them into memory. 4. Treat memory like code: PR review, ownership, and periodic cleanup (remove dead rules). 5. For UI changes, confirm the specific values (colors, prices, text) before starting implementation to avoid rework. 6. For feature delivery, prefer one worktree per feature, run project quality gates, then open one focused PR.

Execution Workflow (Worktree + Gate + PR)

When repositories include a workflow script (for example scripts/git/feature-workflow.sh), prefer this sequence for AI coding sessions:

# 1) Create isolated branch/worktree
./scripts/git/feature-workflow.sh start <feature-slug>
cd .worktrees/<feature-slug>

# 2) Implement + commit
git add -A
git commit -m "feat: <summary>"

# 3) Run project quality gate (example)
../../scripts/git/feature-workflow.sh gate

# 4) Open PR (gate may run again)
../../scripts/git/feature-workflow.sh pr --title "feat: <summary>"

If no helper script exists, use native git worktrees and apply the same policy:

• one feature per worktree
• one focused PR per feature
• run repo-specific gate(s) before PR creation

Rules With Optional Path Scope

Create .claude/rules/testing.md, .claude/rules/security.md, etc. If a rule only applies to a slice of the repo, scope it:

---
paths:
  - "src/api/**/*.ts"
---

Commands (Claude Code)

• > /memory to view and directly edit memories.
• > /init to bootstrap project memory (see official docs for current behavior).

Commands (Codex)

• Edit AGENTS.md directly; no special memory command is required.

Cross-Platform Strategy (AGENTS.md + CLAUDE.md)

If you support multiple coding assistants, keep one canonical file and mirror it:

• macOS/Linux: CLAUDE.md should be a symlink to AGENTS.md.
• Windows: prefer copying (or a small sync script) over symlinks unless Developer Mode is enabled.

Avoid tool-specific claims in the memory file; keep it portable and strictly project-focused.

Token-Budget Profile for Project Memory

When sessions repeatedly include very large memory payloads, apply this compact profile.

Compact Profile Rules

1. Keep AGENTS.md short (target 50-120 lines). 2. Move long catalogs/checklists to skill docs and reference them by path. 3. Keep one canonical policy statement per topic; link instead of repeating. 4. Prefer "read-on-demand" instructions over embedding full inventories in every session. 5. Maintain a short runtime memory and a fuller reference doc when needed.

Suggested Split

• AGENTS.md (runtime): project goal, hard constraints, workflow rules, critical safety constraints.
• docs/* or skill references: long lists, examples, optional playbooks, large inventories.

Quality Gate

If startup memory exceeds practical context budgets, trim before adding new rules.

Validation (Fast Checks)

• Run the bundled linter: bash frameworks/shared-skills/skills/agents-project-memory/scripts/lint_claude_memory.sh .
• Manually scan for unresolved @imports and secrets before merging memory changes.

Resources

Related Skills

Fact-Checking

• Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.
• Prefer primary sources; report source links and dates for volatile information.
• If web access is unavailable, state the limitation and mark guidance as unverified.

Large Codebase Strategy (100K-1M LOC)

Configuration patterns for enterprise-scale codebases with Claude Code and Codex. Use AGENTS.md as the primary memory file and symlink CLAUDE.md to it.

---

Overview

Large codebases require hierarchical documentation, strategic context loading, and careful token management. This guide covers patterns for 100K-1M+ line codebases.

---

Hierarchical Documentation Structure

enterprise-app/
├── AGENTS.md                    # Primary memory file
├── CLAUDE.md                    # Symlink → AGENTS.md
├── .claude/
│   ├── rules/
│   │   ├── security.md          # Global security rules
│   │   ├── testing.md           # Global testing standards
│   │   └── code-style.md        # Global style guide
│   └── settings.json
│
├── packages/
│   ├── api/
│   │   ├── AGENTS.md              # API-specific context
│   │   └── CLAUDE.md              # Symlink → AGENTS.md
│   ├── web/
│   │   ├── AGENTS.md              # Frontend-specific context
│   │   └── CLAUDE.md              # Symlink → AGENTS.md
│   ├── mobile/
│   │   ├── AGENTS.md              # Mobile-specific context
│   │   └── CLAUDE.md              # Symlink → AGENTS.md
│   └── shared/
│       ├── AGENTS.md              # Shared library context
│       └── CLAUDE.md              # Symlink → AGENTS.md
│
└── services/
    ├── auth/
    │   ├── AGENTS.md              # Auth service context
    │   └── CLAUDE.md              # Symlink → AGENTS.md
    ├── payments/
    │   ├── AGENTS.md              # Payments context
    │   └── CLAUDE.md              # Symlink → AGENTS.md
    └── notifications/
        ├── AGENTS.md              # Notifications context
        └── CLAUDE.md              # Symlink → AGENTS.md

---

Root Memory File Template (AGENTS.md / CLAUDE.md)

Keep root file under 100 lines. Focus on navigation and high-level architecture.

# Enterprise App

Monorepo with 500K+ LOC across 12 packages.

## Quick Navigation

| Package | Purpose | Memory File |
|---------|---------|-----------|
| api | REST/GraphQL backend | @packages/api/AGENTS.md |
| web | Next.js frontend | @packages/web/AGENTS.md |
| mobile | React Native app | @packages/mobile/AGENTS.md |
| shared | Shared utilities | @packages/shared/AGENTS.md |

Keep `AGENTS.md` as primary and symlink `CLAUDE.md` to it. Keep the same @imports in the primary file.

## Architecture Overview

- **Monorepo**: Turborepo + pnpm workspaces
- **Backend**: Node.js + TypeScript + PostgreSQL
- **Frontend**: Next.js 16 + React 19
- **Mobile**: React Native + Expo

## Critical Rules (All Packages)

1. All code must pass `pnpm lint` and `pnpm test`
2. No direct database access outside `/packages/api`
3. Shared types MUST go in `/packages/shared`
4. Security rules: @.claude/rules/security.md

## When Working Here

- In Claude Code, use `/memory` to check loaded memory
- Navigate to specific package before detailed work
- Reference package-specific memory files for domain context

---

Package-Level Memory File Template (AGENTS.md / CLAUDE.md)

Each package gets focused, domain-specific context.

# API Package

REST and GraphQL API server.

## Stack

- Node.js 24 LTS
- Fastify 5.x + tRPC
- PostgreSQL 18 + Prisma 6
- Redis for caching

## Directory Structure

packages/api/ ├── src/ │ ├── routes/ # HTTP endpoints │ ├── services/ # Business logic │ ├── repositories/ # Data access │ └── middleware/ # Auth, validation ├── prisma/ │ └── schema.prisma # Database schema └── tests/ ├── unit/ └── integration/

## Patterns

- Repository pattern for data access
- Service layer for business logic
- Zod for request validation
- Prisma for ORM

## Testing

- Unit: Vitest
- Integration: Supertest + test DB
- Coverage target: 80%

## When Working Here

1. Run `pnpm prisma generate` after schema changes
2. Add migrations with `pnpm prisma migrate dev`
3. All endpoints need Zod schemas
4. See @tests/fixtures for test data patterns

---

Context Loading Strategy

Automatic Loading (Claude Code)

Claude Code automatically loads:

• Root CLAUDE.md
• .claude/rules/*.md files
• Subdirectory CLAUDE.md when you access files there

Codex Notes

Codex reads AGENTS.md in the working directory. For package-level context, run Codex from that package directory or mirror the package context into the root file.

Manual Context Management

# Check what's loaded
/memory

# Navigate to package for focused context
cd packages/api

# Edit/view memory
/memory

---

Token Budget Management

Estimation

Budget Allocation (200K context)

---

File Reference Patterns

From Root

## Package Docs
@packages/api/AGENTS.md
@packages/web/AGENTS.md

## Architecture
@docs/architecture/overview.md
@docs/architecture/data-flow.md

From Package

## API Routes
@src/routes/README.md

## Testing
@tests/README.md

## Root Standards
@../../.claude/rules/security.md

---

Monorepo Patterns

Turborepo Setup

# Root memory file (AGENTS.md / CLAUDE.md)

## Turbo Commands

- `pnpm build` - Build all packages
- `pnpm dev` - Start dev servers
- `pnpm test` - Run all tests
- `pnpm lint` - Lint all packages

## Package Dependencies

shared → api, web, mobile api → (standalone) web → shared mobile → shared

Package Isolation

Each package memory file should: 1. Be self-contained for that domain 2. Reference shared standards via @ 3. Not duplicate root-level rules

---

Performance Tips

Keep Memory Files Small

• Root memory file: <100 lines
• Package memory file: <150 lines
• Rule files: <50 lines each

Use @references

Instead of duplicating content:

# Bad - duplicates content
[paste entire style guide here]

# Good - reference external file
See @docs/style-guide.md for code style.

Strategic Navigation

# Don't work from root on large changes
cd packages/api

# Now Claude loads API-specific context
# and you have more token budget for code

---

Scaling Checklist

• [ ] Root memory file is navigation-focused (<100 lines)
• [ ] Each package has focused memory file
• [ ] Global rules in .claude/rules/
• [ ] No duplicated content across files
• [ ] @references for detailed docs
• [ ] Token budget allows for code context
• [ ] /memory shows expected files

---

Example: 500K LOC Migration

Before (Single File)

# App (500K LOC)

[2000 lines of everything]

After (Hierarchical)

AGENTS.md (80 lines - navigation)
├── .claude/rules/ (3 files, ~150 lines total)
├── packages/api/AGENTS.md (100 lines)
├── packages/web/AGENTS.md (120 lines)
├── packages/mobile/AGENTS.md (90 lines)
└── packages/shared/AGENTS.md (60 lines)

Total: ~600 lines across 8 files
Loaded per session: ~200-400 lines (context-dependent)

---

Related Resources

• memory-patterns.md - Common memory patterns
• memory-examples.md - Full examples
• agents-skills - Skill creation

Project Memory Full Examples (AGENTS.md / CLAUDE.md)

Complete, production-ready examples for different project types.

Use these examples as the content for AGENTS.md (Codex). If you support both tools, keep a single file by symlinking CLAUDE.md to AGENTS.md.

---

Example 1: Next.js SaaS Application

# SalesMate CRM

B2B sales pipeline management platform.

## Architecture

- **Frontend**: Next.js 16 (App Router), React 19, TypeScript, Tailwind CSS
- **Backend**: Next.js API Routes, Prisma, PostgreSQL
- **Auth**: NextAuth.js with Google/GitHub OAuth
- **Payments**: Stripe
- **Infrastructure**: Vercel, Neon PostgreSQL

## Directory Structure

\`\`\`
src/
├── app/              # App Router pages
│   ├── (auth)/       # Auth routes (login, register)
│   ├── (dashboard)/  # Protected routes
│   └── api/          # API routes
├── components/       # React components
│   ├── ui/           # shadcn/ui components
│   └── features/     # Feature components
├── lib/              # Utilities
│   ├── db.ts         # Prisma client
│   └── auth.ts       # Auth utilities
└── prisma/           # Database schema
\`\`\`

## Commands

- `pnpm dev` - Start development server
- `pnpm build` - Production build
- `pnpm test` - Run Vitest tests
- `pnpm db:push` - Push schema changes
- `pnpm db:studio` - Open Prisma Studio

## Code Standards

- TypeScript strict mode, no `any`
- Use `unknown` for untyped data
- Zod for runtime validation
- Server Actions for mutations
- React Query for data fetching

## Testing

- Vitest for unit tests
- Testing Library for components
- Playwright for E2E (critical paths only)
- 80% coverage for /lib and /components

## Git Workflow

- Branch: `feat/`, `fix/`, `chore/`
- Conventional commits required
- PR required, 1 approval minimum
- Squash merge to main

## Agent Preferences

- Use `frontend-engineer` for UI work
- Use `backend-engineer` for API routes
- Use `sql-engineer` for Prisma queries

---

Example 2: Python FastAPI Backend

# OrderFlow API

Order management microservice for e-commerce platform.

## Architecture

- **Framework**: FastAPI 0.109+
- **Database**: PostgreSQL with SQLAlchemy 2.0
- **Cache**: Redis
- **Queue**: Celery with Redis broker
- **Auth**: JWT with python-jose

## Directory Structure

\`\`\`
src/
├── api/
│   ├── v1/           # API version 1
│   │   ├── orders/   # Order endpoints
│   │   └── products/ # Product endpoints
│   └── deps.py       # Dependencies
├── core/
│   ├── config.py     # Settings
│   └── security.py   # Auth utilities
├── db/
│   ├── models/       # SQLAlchemy models
│   └── session.py    # Database session
├── schemas/          # Pydantic schemas
├── services/         # Business logic
└── tests/
\`\`\`

## Commands

- `uv run uvicorn src.main:app --reload` - Development
- `uv run pytest` - Run tests
- `uv run alembic upgrade head` - Run migrations
- `uv run ruff check .` - Lint code
- `uv run mypy .` - Type check

## Code Standards

- Python 3.12+
- Type hints required
- Pydantic for validation
- Dependency injection via FastAPI Depends
- async/await for I/O operations

## Testing

- pytest with pytest-asyncio
- Factory Boy for fixtures
- 90% coverage for services/
- Integration tests for API endpoints

## API Conventions

- RESTful resource naming
- Pagination: `?page=1&per_page=20`
- Errors: RFC 7807 Problem Details
- Versioning: URL path `/api/v1/`

---

Example 3: React Native Mobile App

# FitTrack

Fitness tracking mobile application.

## Architecture

- **Framework**: React Native 0.73+, Expo SDK 50
- **Navigation**: Expo Router
- **State**: Zustand + React Query
- **Styling**: NativeWind (Tailwind for RN)
- **Backend**: Supabase

## Directory Structure

\`\`\`
app/
├── (tabs)/           # Tab navigation
├── (auth)/           # Auth screens
└── _layout.tsx       # Root layout
components/
├── ui/               # Base components
└── features/         # Feature components
lib/
├── supabase.ts       # Supabase client
└── hooks/            # Custom hooks
\`\`\`

## Commands

- `npx expo start` - Start Expo dev server
- `npx expo run:ios` - Run on iOS simulator
- `npx expo run:android` - Run on Android emulator
- `npm test` - Run Jest tests
- `eas build --profile preview` - Build preview

## Code Standards

- TypeScript strict
- Functional components only
- Custom hooks for logic extraction
- Avoid inline styles (use NativeWind)

## Testing

- Jest + React Native Testing Library
- Detox for E2E (iOS only)
- Test critical user flows

## Agent Preferences

- Use `mobile-engineer` for all work
- Use `frontend-engineer` for shared logic

---

Example 4: Infrastructure/DevOps

# CloudPlatform Infrastructure

AWS infrastructure managed with Terraform.

## Architecture

- **IaC**: Terraform 1.6+
- **Cloud**: AWS (us-east-1, eu-west-1)
- **Kubernetes**: EKS 1.29
- **CI/CD**: GitHub Actions
- **Monitoring**: Datadog

## Directory Structure

\`\`\`
terraform/
├── modules/          # Reusable modules
│   ├── vpc/
│   ├── eks/
│   └── rds/
├── environments/
│   ├── dev/
│   ├── staging/
│   └── prod/
└── global/           # Shared resources
kubernetes/
├── base/             # Kustomize base
└── overlays/         # Environment overlays
\`\`\`

## Commands

- `terraform init` - Initialize
- `terraform plan -var-file=env.tfvars` - Plan
- `terraform apply -var-file=env.tfvars` - Apply
- `kubectl apply -k overlays/dev` - Deploy to dev

## Standards

- Terraform fmt before commit
- tfsec for security scanning
- Cost estimation required for large changes
- Blue-green deployments only

## Tagging

All resources must have:
- Environment: dev/staging/prod
- Team: platform
- CostCenter: infrastructure

## Agent Preferences

- Use `devops-engineer` for all work
- Use `security-specialist` for IAM/security

---

Example 5: Monorepo with Turborepo

# Acme Platform

Monorepo for Acme web applications.

## Architecture

- **Build**: Turborepo
- **Package Manager**: pnpm
- **Apps**: web (Next.js), admin (Next.js), docs (Nextra)
- **Packages**: ui, config, tsconfig, utils

## Workspace Structure

\`\`\`
apps/
├── web/              # Main website
├── admin/            # Admin dashboard
└── docs/             # Documentation
packages/
├── ui/               # Shared components
├── config/           # ESLint, Prettier configs
├── tsconfig/         # Shared TS configs
└── utils/            # Shared utilities
\`\`\`

## Commands

- `pnpm dev` - Start all apps
- `pnpm build` - Build all
- `pnpm dev --filter=web` - Start specific app
- `pnpm test` - Test all packages
- `pnpm lint` - Lint all

## Standards

- Shared UI components in packages/ui
- No direct cross-app imports
- Use workspace protocol: "workspace:*"
- Changesets for versioning

## When Working Here

1. Check which workspace you're in
2. Run commands from root with --filter
3. Test affected packages: `turbo run test --affected`
4. Update CHANGELOG via changesets

---

Example 6: Behavioral Rules File

Standalone rule file for .claude/rules/coding-behavior.md to prevent common AI failure modes. Based on patterns from Andrej Karpathy's agentic coding observations.

# Coding Behavior Rules

Rules for disciplined, human-supervised agentic coding.

## Before Implementation

### Surface Assumptions
Before implementing anything non-trivial, explicitly state assumptions:

ASSUMPTIONS I'M MAKING: 1. [assumption] 2. [assumption] → Correct me now or I'll proceed with these.

### Manage Confusion
When encountering inconsistencies or unclear specs:
1. STOP—do not proceed with a guess
2. Name the specific confusion
3. Present the tradeoff or ask the clarifying question
4. Wait for resolution before continuing

### Plan First
For multi-step tasks, emit a lightweight plan:

PLAN: 1. [step] — [why] 2. [step] — [why] → Executing unless you redirect.

## During Implementation

### Scope Discipline
Touch only what you're asked to touch.

DO NOT:
- Remove comments you don't understand
- "Clean up" code orthogonal to the task
- Refactor adjacent systems as side effects
- Delete code that seems unused without approval

### Simplicity Enforcement
Before finishing any implementation, verify:
- Can this be done in fewer lines?
- Are these abstractions earning their complexity?
- Would a senior dev say "why didn't you just..."?

Prefer the boring, obvious solution. Cleverness is expensive.

### Push Back When Warranted
When the proposed approach has clear problems:
- Point out the issue directly
- Explain the concrete downside
- Propose an alternative
- Accept the decision if overridden

Sycophancy is a failure mode.

## After Changes

### Change Summary
After any modification, summarize:

CHANGES MADE:

• [file]: [what changed and why]

INTENTIONALLY UNTOUCHED:

• [file]: [left alone because...]

POTENTIAL CONCERNS:

• [any risks or things to verify]

### Dead Code Hygiene
After refactoring:
- Identify code that is now unreachable
- List it explicitly
- Ask: "Should I remove these now-unused elements: [list]?"

Don't leave corpses. Don't delete without asking.

Use case: Add this file when you notice Claude:

• Making assumptions without checking
• Over-engineering simple solutions
• Touching files outside the task scope
• Agreeing too readily to questionable approaches
• Not surfacing tradeoffs on non-obvious decisions

---

Example 7: Cross-Platform Memory (AGENTS.md + CLAUDE.md)

Complete setup for teams using multiple AI coding assistants with shared behavioral rules.

File Structure

acme-app/
├── AGENTS.md                    # Primary memory file
├── CLAUDE.md                    # Symlink → AGENTS.md
├── .claude/
│   ├── rules/
│   │   ├── coding-behavior.md   # Karpathy-style behavioral rules
│   │   ├── security.md
│   │   └── testing.md
│   └── settings.json
└── docs/
    └── architecture.md

AGENTS.md (Primary)

# Acme App

E-commerce platform with Next.js frontend and Node.js API.

## Quick Start

- `pnpm dev` - Start development
- `pnpm test` - Run tests
- `pnpm build` - Production build

## Architecture

- **Frontend**: Next.js 16, React 19, TypeScript, Tailwind
- **Backend**: Node.js, Fastify, Prisma, PostgreSQL
- **Infrastructure**: Vercel, Neon

See @docs/architecture.md for details.

## Code Standards

- TypeScript strict mode, no `any`
- Prettier + ESLint (run on save)
- Conventional commits required
- 80% test coverage minimum

## Behavioral Rules

@.claude/rules/coding-behavior.md

## Security

@.claude/rules/security.md

## Testing

@.claude/rules/testing.md

## AI Tool Notes

This file works with Codex (AGENTS.md) and Claude Code (CLAUDE.md via symlink). Keep `AGENTS.md` as the single source of truth.

- **Claude Code**: Full support for .claude/rules/ and skills
- **Codex CLI**: Reads AGENTS.md, rules via @imports
- **Cursor**: Copy .claude/rules/coding-behavior.md to .cursorrules if needed

Setup Script

#!/bin/bash
# setup-ai-tools.sh - Initialize cross-platform AI memory

# Create directories
mkdir -p .claude/rules docs

# Create symlink (CLAUDE.md → AGENTS.md)
ln -sf AGENTS.md CLAUDE.md

# Create behavioral rules
cat > .claude/rules/coding-behavior.md << 'EOF'
# Coding Behavior Rules

## Before Implementation
- Surface assumptions explicitly before proceeding
- STOP on confusion—name it, wait for resolution
- Emit lightweight plan for multi-step tasks

## During Implementation
- Touch only what's asked (no unsolicited cleanup)
- Prefer simple, boring solutions over clever ones
- Push back on bad ideas directly

## After Changes
- Summarize: CHANGES MADE / UNTOUCHED / CONCERNS
- List dead code explicitly, ask before deleting
EOF

echo "✓ Created AGENTS.md + CLAUDE.md symlink"
echo "✓ Created .claude/rules/coding-behavior.md"
echo ""
echo "Next: Edit AGENTS.md with your project details"

Verification

# Verify symlink
ls -la AGENTS.md
# Should show: CLAUDE.md -> AGENTS.md

# Verify both files have same content
diff AGENTS.md CLAUDE.md
# Should show no output (identical)

# Test with Claude Code
claude "What are my behavioral rules?"

# Test with Codex CLI (if installed)
codex "What are my behavioral rules?"

Use case: Teams supporting both Codex and Claude Code, wanting consistent AI behavior across all tools without maintaining duplicate documentation.

Project Memory Patterns (AGENTS.md / CLAUDE.md)

Common patterns for effective project memory configuration.

Use these templates as the content for AGENTS.md (Codex). If you support both tools, keep AGENTS.md as the single source of truth and symlink CLAUDE.md to it.

---

Pattern 1: Minimal Core Memory

Best for small projects. Keep the primary memory file under 50 lines.

# Project Name

Brief one-line description.

## Stack
- Frontend: React, TypeScript
- Backend: Node.js, PostgreSQL

## Commands
- `npm run dev` - Start development
- `npm test` - Run tests
- `npm run build` - Production build

## Code Standards
- TypeScript strict mode
- Prettier for formatting
- ESLint for linting

When to use: Projects with <10 files, solo developers, simple architectures.

---

Pattern 2: Team Standards Memory

For teams needing consistent conventions across developers.

# Project Name

## Architecture
- Monorepo with Turborepo
- Shared packages in /packages
- Apps in /apps

## Git Workflow
- Branch from `main`
- PR required for all changes
- Squash merge only
- Conventional commits: feat:, fix:, chore:

## Code Review
- 1 approval minimum
- CI must pass
- No console.log in production code

## Testing
- Unit tests for utilities
- Integration tests for APIs
- E2E for critical paths
- 80% coverage minimum

When to use: Teams of 2+, shared codebases, CI/CD pipelines.

---

Pattern 3: Reference-Heavy Memory

Use @ imports for detailed documentation.

# Project Name

High-level overview only in this file.

## Quick Reference
- @docs/architecture.md - System design
- @docs/api-patterns.md - API conventions
- @docs/testing-guide.md - Test requirements
- @.claude/agents/README.md - Available agents

## Current Sprint
- Feature X in progress
- Bug Y needs fixing

## Agent Preferences
- Use `backend-engineer` for API work
- Use `test-architect` for coverage

When to use: Large codebases, detailed documentation exists, token optimization needed.

---

Pattern 4: Monorepo Memory

Hierarchical memory for multi-package repositories.

monorepo/
├── AGENTS.md              # Primary memory file
├── CLAUDE.md              # Symlink → AGENTS.md
├── packages/
│   ├── web/
│   │   ├── AGENTS.md      # Web-specific
│   │   └── CLAUDE.md      # Symlink → AGENTS.md
│   ├── api/
│   │   ├── AGENTS.md      # API-specific
│   │   └── CLAUDE.md      # Symlink → AGENTS.md
│   └── shared/
│       ├── AGENTS.md      # Shared lib
│       └── CLAUDE.md      # Symlink → AGENTS.md

Root memory file (AGENTS.md or CLAUDE.md):

# Monorepo Standards

## Shared Rules
- All packages use TypeScript
- Shared ESLint config
- Turborepo for builds

## Package Commands
- `turbo run build` - Build all
- `turbo run test` - Test all
- `turbo run dev --filter=web` - Dev specific

Package memory file (AGENTS.md or CLAUDE.md):

# Web Package

Inherits from root. Additional rules:

## Stack
- Next.js 16 App Router
- Tailwind CSS
- Zustand for state

## Testing
- Vitest for unit
- Playwright for E2E

---

Pattern 5: Local Development Overrides

Use CLAUDE.local.md for personal preferences (git-ignored). If Codex is your primary tool, keep local overrides in a git-ignored notes file and merge into AGENTS.md only when needed.

<!-- CLAUDE.local.md -->

# My Local Setup

## Environment
- Using Docker for database
- Node 20 instead of 18
- DATABASE_URL=postgresql://localhost:5432/dev

## Preferences
- Verbose logging enabled
- Skip slow E2E tests: --skip-e2e
- Use experimental features

## Debugging Notes
- Auth service on port 3001
- Redis on port 6379

---

Anti-Patterns to Avoid

Don't: Generic Instructions

# Bad Example
- Write clean code
- Follow best practices
- Be efficient

Don't: Duplicate Code Comments

# Bad Example
## UserService
The UserService handles user operations...
(already documented in code)

Don't: Outdated Information

# Bad Example
## Database
Using MySQL 5.7  # Actually migrated to PostgreSQL

Don't: Sensitive Data

# Bad Example
API_KEY=sk-12345...  # Never put secrets here

---

Pattern 6: Behavioral Coding Rules

Explicit cognitive guardrails to prevent common AI failure modes (assumption errors, scope creep, over-engineering).

File: .claude/rules/coding-behavior.md

# Coding Behavior Rules

## Before Implementation

- **Surface assumptions**: List them explicitly, ask for correction before proceeding
- **Manage confusion**: STOP when encountering ambiguity, name the specific confusion, wait for resolution
- **Inline planning**: For multi-step tasks, emit lightweight plan before executing

## During Implementation

- **Scope discipline**: Touch only what's asked—no unsolicited cleanup, refactoring, or "improvements"
- **Simplicity enforcement**: Prefer boring, obvious solutions; if 100 lines suffice, don't write 1000
- **Push back when warranted**: Point out problems directly; "Of course!" to bad ideas helps no one

## After Changes

- **Change summary**: Report CHANGES MADE / INTENTIONALLY UNTOUCHED / POTENTIAL CONCERNS
- **Dead code hygiene**: Identify unreachable code explicitly, ask before deleting
- **Preserve unknowns**: Don't remove code or comments you don't fully understand

When to use: Teams experiencing AI over-engineering, scope creep, silent assumption errors, or sycophantic responses.

Key failure modes this prevents: 1. Making wrong assumptions without checking 2. Not surfacing inconsistencies or tradeoffs 3. Being sycophantic ("Of course!") to bad ideas 4. Overcomplicating code and APIs 5. Modifying code orthogonal to the task

---

Pattern 7: Cross-Platform Memory (AGENTS.md + CLAUDE.md)

Share project memory and behavioral rules across multiple AI coding tools.

Directory Structure

your-project/
├── AGENTS.md                    # Primary (Codex) or mirror
├── CLAUDE.md                    # Primary (Claude Code) or mirror
└── .claude/
    └── rules/
        ├── coding-behavior.md   # Behavioral rules (tool-agnostic)
        ├── security.md          # Security rules
        └── testing.md           # Testing standards

Setup Commands

macOS/Linux (symlink):

# AGENTS.md primary
ln -sf AGENTS.md CLAUDE.md

Windows (copy or script):

# Copy approach (simpler, requires manual sync)
Copy-Item AGENTS.md CLAUDE.md

# Or create sync script in package.json
# "sync:agents": "cp AGENTS.md CLAUDE.md"

Unified Memory File Template

# Project Name

Cross-platform instructions for AI coding assistants.

## Overview
Brief project description...

## Architecture
@docs/architecture.md

## Code Standards
- TypeScript strict mode
- Prettier + ESLint
- 80% test coverage

## Behavioral Rules
@.claude/rules/coding-behavior.md

## Testing
@.claude/rules/testing.md

## Tool-Specific Notes

### Claude Code
- Full `.claude/rules/` support
- Skills available in `.claude/skills/`

### Codex CLI
- Reads AGENTS.md directly
- Use @imports only if your Codex tooling supports them; otherwise inline essentials

### Cursor
- Copy rules to `.cursorrules` if @imports unsupported

Tool Compatibility Matrix

Best Practices

1. Single source of truth: Keep AGENTS.md as primary, symlink CLAUDE.md 2. Tool-agnostic rules: Write rules that work for any AI assistant 3. @import for depth: Reference detailed docs, don't duplicate 4. Git-track symlinks: Symlinks work in git repos across platforms

When to use: Teams using multiple AI coding assistants (Claude Code + Cursor, Claude Code + Codex CLI, etc.) who want consistent behavior across all tools.

---

Memory Size Guidelines

Rule: If the primary memory file exceeds 150 lines, split into @referenced files.