What should I put in a CLAUDE.md file?

Five things: exact project commands (build, test, lint), a map of where code lives, conventions with the reason attached, versions of load-bearing dependencies, and boundaries the agent must not cross. Keep it under roughly a thousand tokens and prune stale facts the moment they change.

What is the difference between CLAUDE.md and AGENTS.md?

Content-wise, nothing: both are plain markdown loaded at session start. CLAUDE.md is read by Claude Code; AGENTS.md is a cross-tool convention read by Cursor, Codex, and others. Many teams maintain one file and mirror or symlink the other name so every tool picks it up.

Why does my coding agent keep forgetting my instructions?

Because chat is not memory. Instructions live in a fixed-size context window where they get buried under file reads and tool output, and they vanish entirely when the session ends. Durable instructions belong in a context file the agent loads every session.

How long should a CLAUDE.md file be?

Long enough to hold commands, map, conventions, versions, and boundaries; short enough that you would not mind paying for it in every single session, because you do. Under a thousand tokens is a good target. If one subsystem needs depth, link a separate doc instead of inlining it.

Do bigger context windows fix context rot?

They delay the overflow, not the dilution. An instruction buried under 300K tokens of logs competes for attention just like one buried under 100K. Whatever the window size, a lean session with durable facts in a context file beats a marathon session with everything in chat.

CodeSmith

blog // tools

AI Coding Developer Workflow

Context Engineering for Coding Agents: CLAUDE.md, AGENTS.md, and Token Budgets

Sourabh

July 18, 2026

14 min read

Share this article

A 200K window. Choose how you run your sessions and watch the budget.

Context file (CLAUDE.md / AGENTS.md)

How the agent reads code

Session length

Tool and test output

Used: 39K of 200KWorking space left: 161K

System prompt + tools (15K, fixed)

Instructions hold

Plenty of working space, and your durable facts ride along in a lean context file. This is the setup where corrections stick and style stays consistent.

Paste your CLAUDE.md or AGENTS.md. It stays in your browser.

Loading interactive content...

AI Coding

Sourabh

July 12, 2026

15 min read

Vibe Coding to Engineered Workflow: A Practical Guide to AI Coding Agents

The agent one-shots your feature on Monday and quietly rewrites your auth module on Tuesday. Here is the workflow that keeps the speed without the wreckage: plan-first prompting, reviewable diffs, and verification the agent runs itself. With interactive tools to grade your own prompts.

Developer Workflow Productivity

Read

TOON vs YAML: Reduce LLM Token Costs & When to Use Each

Data Formats

Sourabh

November 27, 2025

11 min read

TOON vs YAML: Reduce LLM Token Costs & When to Use Each

Discover how TOON (Token-Oriented Object Notation) can reduce LLM token usage by 30–60% compared to YAML, and learn when to use each format for optimal performance and cost efficiency.

LLM YAML

Read

Related Posts

Vibe Coding to Engineered Workflow: A Practical Guide to AI Coding Agents

TOON vs YAML: Reduce LLM Token Costs & When to Use Each