Why Smart AI Keeps Forgetting and How Externalizing Decisions to Files Solves It

01 | How fragile is consensus in a conversation

When you spend time explaining a project’s background to an AI—e.g., using React with Zustand for state management, routing all API calls through api/, and handling errors via useErrorBoundary —the AI may produce correct code in that session. However, opening a new conversation starts with a blank context window, so the AI forgets the previously established conventions and reverts to default patterns like using fetch, useState, and generic try‑catch error handling. Even if you repeat the earlier guidelines, the AI may still miss implicit agreements such as "do not import Redux in components" because each session treats the conversation as a fresh sheet of paper. This volatility is normal: conversational consensus evaporates after the dialogue ends.

The root cause is that the AI only knows what is present in the current context window; anything not written on that page is unknown.

02 | Why turning decisions into files solves the problem

By writing conventions into a fixed file that the AI loads at startup, the same decisions become a stable input to the context window for every session. This transforms volatile, ephemeral consensus into persistent, reusable decisions.

Conversation consensus:
  Conversation 1 → consensus → end → consensus disappears
  Conversation 2 → consensus → end → consensus disappears
  …
  Conversation N → start from zero

File consensus:
  Write once CLAUDE.md → auto‑load each conversation → consensus persists
  Update file → next conversation sees the change
  New teammate → open file to see all conventions

Tools such as Claude Code’s CLAUDE.md, Cursor’s .cursorrules, and GitHub Copilot’s .github/copilot‑instructions.md all serve the same purpose: providing the AI with a stable, repeatable set of decisions.

03 | Practical file hierarchy

Different tools use different filenames but share a three‑level hierarchy.

Claude Code – CLAUDE.md

~/.claude/CLAUDE.md          # user‑level: applies to all projects
/your-project/CLAUDE.md       # project‑level: applies to the current project
/your-project/src/CLAUDE.md   # directory‑level: applies to a specific subdirectory

User‑level files store personal preferences (e.g., always use TypeScript). Project‑level files store project‑wide conventions, and directory‑level files store module‑specific rules.

Cursor – .cursorrules

/your-project/.cursorrules   # project‑level only

GitHub Copilot – copilot‑instructions.md

/your-project/.github/copilot‑instructions.md

All three formats are plain Markdown without syntax restrictions; the key is to write clear rules that the AI can obey.

04 | Engineering guidelines: what to write and what not to write

What belongs in the file – architecture decisions and technical conventions that rarely change:

## Technical stack
- Frontend framework: React 18 + TypeScript (strict mode)
- State management: Zustand (no Redux, no MobX)
- Styling: Tailwind CSS (no CSS‑in‑JS)
- Request wrapper: all calls go through src/api/ (no direct fetch in components)

## Code conventions
- TypeScript: disallow <code>any</code>, use <code>unknown</code> + type guards
- Function naming: verb‑first, camelCase (e.g., getUserById)
- Component files: one component per file, filename matches component name
- Import order: third‑party → internal modules → relative paths, separated by blank lines

## Directory layout
src/
  api/        # API layer, token injection, error formatting
  components/  # Pure UI components, no business logic
  features/    # Feature modules, organized by domain
  hooks/        # Custom hooks prefixed with "use"
  stores/       # Zustand stores, one file per domain

## Known pitfalls
- Tencent Map SDK v2.1 `setCenter` fails on iOS < 15 → use `panTo`
- WeChat JSSDK must initialize after DOM ready, otherwise signatures may fail

What should NOT be written – concrete implementation details that vary per task:

# Do NOT write things like:
- Step 3: call getUserById with an id parameter
- Add an isLoading state inside UserCard component
- Destructure name and email from the response

The rule of thumb: if a convention applies to *all* tasks, put it in the file; if it only applies to the current task, keep it in the conversation.

05 | Advanced: three‑layer decision file system

Beyond a single CLAUDE.md, a three‑layer system provides granular control.

User‑level – personal preferences across projects:

## My preferences
- I am a backend engineer; I prefer TypeScript over Python
- I dislike redundant comments; no obvious code needs comments
- Variable names must be semantic, no abbreviations unless industry standard (e.g., id, url)
- Answers should give the conclusion first, then details

## My tools
- Package manager: pnpm (no npm, no yarn)
- Testing: Vitest (no Jest)
- Formatting: Prettier + ESLint

Project‑level – project‑wide conventions stored at /project/CLAUDE.md. New team members can open the file to align quickly.

Directory‑level – module‑specific conventions placed in sub‑directories, e.g.:

/project/
  CLAUDE.md               # project‑level conventions
  src/
    api/
      CLAUDE.md           # API‑layer conventions (naming, error handling)
    components/
      CLAUDE.md           # Component‑layer conventions (props naming, classification)

When Claude Code processes files under src/api/, it loads both the project‑level and directory‑level CLAUDE.md, creating a layered effect. This keeps global standards from being polluted by project‑specific details and vice versa.

06 | Framework comparison: file strategies across tools

Different Harness Engineering frameworks implement decision externalization differently.

Spec‑Kit – SPEC.md combines project specifications with AI coding conventions:

/project/
  SPEC.md          # What to build: features, user stories, data model, API design
  CLAUDE.md        # How to build: tech stack, code style, directory rules
  CHANGELOG.md    # Change history

This approach is ideal for greenfield projects where the full specification is written up front.

ECC (Enhanced Claude Coding) – skills files externalizes not only conventions but also AI capabilities:

~/.claude/
  CLAUDE.md          # Global conventions
  commands/          # Custom commands (e.g., /review, /deploy)
  skills/            # Skill files (e.g., code‑review.md, write‑tests.md)

Skill files act as operation manuals, listing the checks AI should perform for tasks like code review or test writing.

GSD (Get Stuff Done) – PLANNING.md focuses on the current iteration’s state:

/project/
  CLAUDE.md          # Coding conventions
  PLANNING.md        # Current iteration goals, progress, next steps
  TASKS.md           # Task breakdown and status

Loading PLANNING.md at the start of a new conversation lets the AI pick up where the last session left off.

07 | Common pitfalls

Pitfall 1: Files become too long, exploding token usage – a 5,000‑word CLAUDE.md consumes 5,000 input tokens per request, quickly becoming costly. Moreover, a long file dilutes attention; the AI must process all content, making important rules harder to surface.

Solution – keep project‑level files to 300–500 words and offload module‑specific rules to directory‑level files.

Pitfall 2: Vague conventions that AI cannot enforce – statements like "code should be concise" or "avoid complex logic" lack concrete criteria, so the AI cannot act on them.

Effective wording example :

# Vague (ineffective)
- Code should be concise and readable
- Names should be meaningful
- Avoid overly long functions

# Specific (effective)
- Functions must not exceed 50 lines
- Variable names use full words, no abbreviations (e.g., config, not cfg)
- Function names start with a verb (e.g., getUserById, not userById)

Pitfall 3: Files are written once and never updated – as projects evolve, outdated conventions (e.g., using Webpack after migrating to Vite) cause mismatches.

Recommendation – treat convention files like code: update them whenever a major architectural decision is made or a technology stack changes.

Summary

Conversational consensus evaporates after each dialogue; the AI starts with a blank context window.

Persisting decisions in files provides a stable input to the context window, preventing forgetfulness.

A three‑layer structure (user‑level → project‑level → directory‑level) balances global preferences with project and module specifics.

Write architecture decisions and technical conventions, not concrete implementation steps.

Keep files concise and specific; vague rules are ineffective, and overly long files waste tokens and attention.

Maintain convention files like code—update them as the architecture evolves.