Eslam HelmyEslam Helmy
•4 min read•Eslam

Build Your Own Dev Agent — Lesson 2: The Foundation: CLAUDE.md + State Files

claude-codedev-agentautomation

The brain is CLAUDE.md -- the master instruction file Claude Code reads at startup. The memory is a set of state files that persist between sessions.

Where You Are

your-project/
  (empty -- we start here)

See It: What CLAUDE.md Does

When Claude Code starts a session, it looks for a CLAUDE.md file in your project root. If it finds one, it reads the entire file and treats it as instructions. This is not a suggestion file. It is a directive. Whatever you write in CLAUDE.md, Claude Code will follow.

This means you can define:

  • What files to read at startup
  • What rules to follow when making decisions
  • What to do after completing a task
  • What never to do

Think of CLAUDE.md as the agent's job description. Without it, Claude Code is a general-purpose assistant. With it, Claude Code becomes your specific agent.

See It: What State Files Do

State files track what the agent knows and what it has done. They live in .claude/ and evolve as you use the agent -- you don't design them upfront. You tell Claude Code "I need to track my tasks" and it creates the file.

Here's what mine evolved into:

  • tasks-active.md -- Current work. You add tasks, the agent moves them to completed when done. Invoked: the agent reads this at every session startup and before running any skill. Skills like the daily planner and meeting ingest write new tasks here.
  • progress.txt -- A running log. Both you and the agent write to it. Invoked: every skill appends a line when it finishes (heartbeat logs, meeting summaries, daily reviews). You add manual notes anytime. The standup generator and daily planner read it to know what happened.
  • preferences.md -- Who you are, how you work, what not to do. Invoked: read at session startup so the agent knows your identity and rules. The inline learning system appends corrections here when you say "don't do X" or correct the agent's style.

These are plain text files. No schema, no database. The key: they're not passive storage. CLAUDE.md tells the agent when to read and write each file. That's what makes them state — they drive behavior.

Build It: Set Up the Foundation

Open your project in Claude Code. Tell it what you need — don't dictate the exact file contents. Claude Code will figure out the structure.

Prompt for Claude Code:

I want to set up a dev agent. Create:

1. A CLAUDE.md in the project root that tells you to:
   - Read .claude/preferences.md, .claude/tasks-active.md, and
     .claude/progress.txt at session startup
   - Resume any in-progress work from tasks-active.md
   - After completing any task, append a line to progress.txt
     and update tasks-active.md
   - Never overwrite progress.txt — append only

2. A .claude/ directory with:
   - preferences.md — my name is [Your Name], I'm a [Your Role].
     Don't push code without approval, don't send messages without
     approval, don't delete files without confirmation.
   - tasks-active.md — one starting task: "Set up dev agent foundation"
   - progress.txt — one entry logging that the foundation was created

Expected output: CLAUDE.md in project root + three files in .claude/. Claude Code creates the structure, formats the files, and fills in the details. You review and adjust.

The key: you described what you need, not how to format it. The files will evolve as you correct the agent — the format you get today won't be the format you have next week.

Checkpoint

Your project should now contain: CLAUDE.md, .claude/preferences.md, .claude/tasks-active.md, .claude/progress.txt.

This is part of the Build Your Own Dev Agent course. ← Previous Lesson | Next Lesson →

Share this post