Agent Development on Code Plato

A Concise Guide to Writing CLAUDE.md

Sun, 13 Sep 2026 00:00:00 +0000

This guide applies equally to AGENTS.md

What CLAUDE.md Is For

First, let’s understand what CLAUDE.md is for. A model is like a newborn. Every time you talk to it, it has no idea who you are, who it is, or what you’ve said before. It learns all of this from the context you pass it. Of course, Claude Code comes with some preset context, so it knows it’s Claude Code, a tool that helps you write code. So at the start of every new session, it knows nothing about your project. The reason it still works reasonably well is that Claude Code’s own preset context teaches it what to do to understand a project before touching it. That’s why it can seem to understand your project quite well, yet still frequently reinvents the wheel. It has a methodology for quickly getting up to speed, but it still can’t know every detail of your project. And you wouldn’t want it to try — that would burn far too many tokens. This is where someone needs to use short, plain language to tell it about the project’s background, architecture, and so on. Doing this has two benefits:

It won’t need to traverse your entire project, saving tokens
It won’t do things that obviously go against your codebase’s intent, or reinvent the wheel This short text is what goes into CLAUDE.md, or AGENTS.md. This guide applies equally to AGENTS.md.

Writing Principles

A good CLAUDE.md should read like: The shortest onboarding guide for a new hire: Imagine you’re onboarding a new hire for a task. Try to convey just enough knowledge, in the fewest words possible, for them to start working without wrecking your codebase. Wording as tight as a résumé: A while back I was job hunting, and I learned from an HR contact how to write a résumé. I racked my brain compressing my 4-page résumé down to 2 pages, cutting almost every redundant word, tightening every sentence until it couldn’t be trimmed further. You should write CLAUDE.md the same way. Highly abstract knowledge: You don’t need to tell Claude Code or Codex CLI how many spaces to indent, or which line of which file has the database connection. Leave a lot of that to hooks — file names and line numbers change all the time. What you should tell the model are highly abstract design principles. Generally speaking, a good CLAUDE.md should be under 200 lines.

Types

Including the CLAUDE.md at your project root, there are actually 3 kinds of CLAUDE.md.

~/.claude/CLAUDE.md — global scope. Used by all of your projects.
./CLAUDE.md — project scope.
./subdirectory/CLAUDE.md — subdirectories can have their own CLAUDE.md too.

Framework

There’s no strict, perfect framework for CLAUDE.md. But drawing on some good examples of CLAUDE.md and related articles, I’ve distilled a reasonably sound structure:

One-line introduction
Architecture
Tech stack
Commands
Conventions
Boundaries
Domain doc map

One-Line Introduction

A brief description of what the project is and roughly what it does. Example:

This is a multi-agent orchestration framework for coordinating parallel Claude Code sub-agents, automating dev/QA workflows on a FastAPI + React codebase.

Architecture

A brief description of the project’s architecture, for example:

## Architecture
- Keep controllers thin — business logic lives in `app/Services/`
- Database access only goes through `app/Repositories/`. No direct Eloquent usage in controllers.
- API resources under `app/Http/Resources/` are responsible for shaping every JSON response.

Tech Stack

A brief description of the project’s tech stack, like:

## Tech Stack
- FastAPI, Python 3.11
- PostgreSQL 15 (async SQLAlchemy 2.0)
- Celery + Redis for background jobs
- Poetry for dependency management

Commands

Common commands for the project, for example:

## Commands
- Dev server: `uvicorn app.main:app --reload`
- Run tests: `pytest -x -v`
- DB migrations: `alembic upgrade head`

Conventions

Abstract conventions that a linter can’t capture, like:

## Conventions
- Boolean variables/properties are prefixed with `is`, `has`, or `should`
- All datetimes are stored and passed as UTC
- Event names follow the `domain.action` naming format

Boundaries

Boundaries on which files can be modified:

## Boundaries
- `legacy/` — old payment system, emergency bug fixes only, no new patterns or refactors
- `src/generated/` — auto-generated by Prisma/GraphQL
- `vendor/`, `third_party/` — third-party code, fix issues by upgrading the dependency version, don't edit directly

Domain Doc Map

A mapping between domain terms and documentation:

## Domain Doc Map
| Mentions | Read |
|---|---|
| billing, stripe, payment, subscription, invoice | docs/billing.md |
| auth, login, session, oauth, jwt | docs/auth.md |
| migration, schema, drizzle, kysely | docs/db-migrations.md |
| feature flag, rollout, kill switch | docs/feature-flags.md |

Putting these examples together, a good CLAUDE.md should look something like this:

This is a multi-agent orchestration framework for coordinating parallel Claude Code sub-agents, automating dev/QA workflows on a FastAPI + React codebase.

## Architecture
- Keep controllers thin — business logic lives in `app/Services/`
- Database access only goes through `app/Repositories/`. No direct Eloquent usage in controllers.
- API resources under `app/Http/Resources/` are responsible for shaping every JSON response.

## Tech Stack
- FastAPI, Python 3.11
- PostgreSQL 15 (async SQLAlchemy 2.0)
- Celery + Redis for background jobs
- Poetry for dependency management

## Commands
- Dev server: `uvicorn app.main:app --reload`
- Run tests: `pytest -x -v`
- DB migrations: `alembic upgrade head`

## Conventions
- Boolean variables/properties are prefixed with `is`, `has`, or `should`
- All datetimes are stored and passed as UTC
- Event names follow the `domain.action` naming format

## Boundaries
- `legacy/` — old payment system, emergency bug fixes only, no new patterns or refactors
- `src/generated/` — auto-generated by Prisma/GraphQL
- `vendor/`, `third_party/` — third-party code, fix issues by upgrading the dependency version, don't edit directly

## Domain Doc Map
| Mentions | Read |
|---|---|
| billing, stripe, payment, subscription, invoice | docs/billing.md |
| auth, login, session, oauth, jwt | docs/auth.md |
| migration, schema, drizzle, kysely | docs/db-migrations.md |
| feature flag, rollout, kill switch | docs/feature-flags.md |

Should You Write a “Never” Section?

You may have seen a section in other guides called “Never,” used to record past mistakes. Sounds good in theory. But I don’t recommend adding this section. That’s because a “Never” section has only the motivation to add, never the motivation to remove. It just keeps growing — even Claude Code itself will add to it, and no one ever trims it. Over time it turns into a graveyard of historical incidents. What I’d suggest instead: when a problem comes up, flip the failure mode around and write it as a positive rule. For instance, instead of “Never do synchronous database writes in webhook/stripe.ts,” write “Database operations only happen inside repository/.”

Trimming

Even if you follow the framework above, for a large project, a long-lived one, or one that already has a CLAUDE.md, you’ll still find it hard to keep the file under 200 lines. That’s when you move to the trimming step. Trimming means moving things out of CLAUDE.md. Here are the destinations and methods, in order:

Custom sub-agents: .claude/agents
Rules folder: .claude/rules
Subdirectory CLAUDE.md: ./subdirectory/CLAUDE.md
Fixed workflows: .claude/skills/
Other docs: docs/ Notice these are numbered. That’s because extraction has a priority order — from specific to abstract, from precise to general.

Custom Sub-agents

Move all guidance related to sub-agents into .claude/agents. For example: You could define an agent dedicated to running integration tests, named integration-tester.md, with content like:

---
name: integration-tester
description: Runs integration tests
tools: Bash
model: sonnet
---

You run and diagnose integration tests. You should follow these steps.....

Rules Folder

Specific rule files can live in .claude/rules. There are two kinds: path-scoped and non-path-scoped. Non-path-scoped rules carry the same priority as CLAUDE.md, for example:

# Security Rules

- All user input is validated at the API boundary
- Secrets and API keys are read from environment variables only
- SQL queries always use parameterized statements

Path-scoped rules only load when the given path condition is met, for example:

---
paths:
 - "tests/**/*.py"
 - "**/*.spec.ts"
---

# Unit Testing Rules

- One assertion concept per test
- Test names describe behavior, not implementation
....

Rules vs. the domain doc map: You might wonder: “Don’t rule files and the domain doc map end up defining the same thing twice?” Yes, that overlap can happen. For instance, you might specify that files under billings/ should follow the billing docs, and also have a row in the domain doc map like | billings | docs/billings.md | — which is indeed redundant. The fix is to split documentation into rules and background. Rule files are highly enforceable and belong in .claude/rules. Background files are comparatively looser and belong in docs/.

Subdirectory CLAUDE.md

Rules specific to certain subdirectories can move into those directories — common cases are sql/, domains/, adapters/ folders. A CLAUDE.md in these directories doesn’t need to follow the standard framework, but it should still stay short.

Fixed Workflows

If there are fixed, sequential operations, turn them into a project-level skill and put it under .claude/skills/.

Other Docs

Everything else goes into the docs/ directory. This directory holds more general documentation — things like a more detailed architecture.md, or ADRs (Architecture Decision Records) under docs/adr/, e.g. docs/adr/0001-migrate-to-drizzle.md.

Getting Started

If you don’t yet have a CLAUDE.md or AGENTS.md, start with these steps:

Run /init to generate a first draft
Revise the draft following the methods above

Also remember to run /doctor periodically going forward to keep optimizing CLAUDE.md.

References

When You Don't Need MCP

Mon, 07 Sep 2026 00:00:00 +0000

The Problem

Job postings keep mentioning MCP, as if everyone doing agent development has to know it
Some people say MCP is too heavyweight and hardly anyone actually uses it
Meanwhile plenty of tutorials say a unified interface via MCP is great

Most tutorials you’ll come across explain what MCP is and why you should use it. After all that explanation, it’s still hard to get an intuitive feel for the trade-offs. So today I’ll flip the question around: when do you not need MCP? That’s a better way to build intuition about it.

What Is MCP

MCP (Model Context Protocol) is an open protocol launched by Anthropic that lets AI applications (agents like Claude Code, Claude Desktop, OpenClaw) discover and call external tools, and read external resources, in a unified way.

That’s the textbook definition. In practice, you can think of MCP as a kind of resource exposed to an agent. Before MCP existed, if you wanted an AI application to connect to services like Google Drive, GitHub, or Slack, every single AI application had to write its own integration code for every external service. MCP is essentially a “standard socket” defined for that connection.

What You’d Use Instead of MCP

If you skip MCP, you still have plenty of other options. The two most important ones:

Function calling: OpenAI introduced function calling in 2023. It’s actually simple — you pass a function signature to the LLM first.

{
 "name": "get_weather",
 "description": "Get the current weather for a specified city",
 "input_schema": {
 ...
 "properties": {"city": {"type": "string"}},
 }
}

Once the LLM knows a tool exists, if it decides during execution that it needs to call this external tool, the result’s content will include an extra tool_use object, and stop_reason will also be set to tool_use. Like this:

{
 "content": [
 {
 "type": "tool_use",
 "name": "get_weather",
 "input": {"city": "new york"}
 }
 ],
 "stop_reason": "tool_use"
}

Then you write the code yourself to actually implement the function call.

if response.stop_reason == "tool_use":
 tool_use = response.content[-1]
 // ... call the weather-lookup function

In real-world work it’s obviously less crude than this — you’d use a framework like LangChain.

CLI: This is really just another form of function calling — except you expose exactly one tool, and you tell the LLM upfront that it’s a bash shell, so it can write whatever command it wants. The advantage is you don’t need to tell the LLM what bash can do or how to use it — the LLM has already read enough material to know how to write bash commands on its own.

But using a CLI comes with real risk, since permission control is hard to get right.

From the Model’s Perspective

First, you need to understand one thing: the model has no idea whether you’re calling it through MCP or through function calling. For example, when you register a weather-lookup tool, if you register it via MCP, here’s what the model sees in its tools list:

{
 "name": "get_weather",
 "description": "Get the current weather for a specified city",
 "input_schema": {
 "type": "object",
 "properties": {
 "city": {"type": "string"}
 }
 }
}

If you use function calling instead, here’s what the model sees:

{
 "name": "get_weather",
 "description": "Get the current weather for a specified city",
 "input_schema": {
 "type": "object",
 "properties": {
 "city": {"type": "string"}
 }
 }
}

Let’s play a little game: can you spot the difference between these two JSON blocks? The answer is there isn’t one. So there’s no need to agonize over whether MCP versus function calling affects the model somehow. As far as the model is concerned, there’s no difference at all.

The Downsides of MCP

If MCP is so great, why not just use it everywhere? Because MCP does have real downsides:

Large context overhead: Once you connect to an MCP server, the full schema (name, parameters, description) for every tool that server exposes gets stuffed into the model’s context window up front — whether or not this particular conversation ever needs it.

Server resource consumption: An MCP server is something that runs continuously and has to stay alive. The more MCP servers you spin up, the more CPU and memory they eat on your machine.

Operational burden: Since an MCP server is a separate process, you’re on the hook for restarting it when it crashes, sequencing startup order across multiple servers, and maintaining internal state over time.

The Upsides of MCP

MCP sounds pretty rough so far. So why do so many companies keep using it anyway? Because despite its downsides, its biggest strength is unifying the integration interface across your project’s resources. A unified interface brings two benefits on its own:

Cleaner calling code: People who don’t build software won’t really feel this benefit, but anyone who does knows immediately how good a unified interface is. Your thousands of lines of legacy spaghetti code can suddenly collapse into a dozen lines. The more interfaces you have, the more bugs get buried, and buried deeper — maintenance becomes endless.

Easier third-party integration: Once every third-party resource is packaged as MCP, integrating them no longer takes a lot of custom effort. There’s nothing technically clever about this — it’s the same idea as standardizing currency or units of measurement. What matters is that someone has to actually go do it.

Conclusion

If your situation matches one of the following:

You want to use a tool built by a third party
You’re using a tool shared across multiple platforms on your team
You need to separate permissions across multiple roles

then MCP is worth considering. Otherwise, a lighter-weight approach — like plain function calling — is enough.