Originally published on

Coding-Agent Instruction Design: The CLAUDE.md File That Prevents Rework

The fastest way to waste a coding agent is to ask it to infer your repository rules from scattered files. It will usually find the package manager. It may find the test command. It will not reliably infer which migration tool is safe, which Docker Compose file is production, which Kubernetes namespace is shared, or which files are generated and should not be edited.

That is why a small CLAUDE.md or equivalent repo instruction file is useful. It turns tribal knowledge into a contract the agent can read before touching code.

This is not executive AI strategy. It is a hands-on habit for developers running real systems with tight budgets: SaaS teams in Bengaluru, Singapore fintech teams, and small APAC platform groups that cannot afford long review loops after every automated change.

What The File Should Do

The file should answer six operational questions:

• What does this repo own?


• Where are the main services?


• Which commands are allowed?


• Which commands are expensive or forbidden?


• Which tests must pass before a change is considered done?


• What should the agent never edit without asking?

Keep it short. A useful file is not a wiki. It is a guardrail.

A Practical Skeleton

Start with this structure:

# Repository Instructions



## Scope

This repo owns the API service, worker, Docker image, and Helm chart.



## Commands

- Install: npm ci

- Unit tests: npm test

- Type check: npm run typecheck

- Build image: docker build -t local/api:test .



## Do Not Edit

- generated/

- migrations already applied in production

- secrets, .env files, or deployment credentials



## Before Finishing

- run unit tests

- mention any tests not run

- list config or migration changes

That small template prevents several common failures: editing generated files, inventing test commands, modifying secrets, or shipping a migration without calling it out.

Add Docker And Kubernetes Boundaries

For infrastructure-heavy repos, add the local runtime rules. A coding agent that sees docker-compose.yml, compose.prod.yml, and a Helm chart may choose the wrong path unless you tell it the intended workflow.

Example:

## Runtime

- Local development uses docker-compose.dev.yml.

- Production deployment uses charts/api, not compose.prod.yml.

- Never change resource requests without explaining expected CPU and memory impact.

- Never create a new namespace; use existing namespace labels.

This matters for cost optimization. A casual CPU request change can raise monthly cluster spend. A missing readiness probe can slow rollouts. A generated manifest edit can vanish in the next build.

Use Concrete Examples

Good instruction files include examples from the repo. If your team uses Prisma, mention the migration command. If the service uses Alembic, mention how migrations are generated and reviewed. If your team has a canary namespace, name it.

Bad:

Run the usual tests.

Good:

Run `npm test -- --runInBand` for unit tests. Run `npm run test:integration` only when API routes, database queries, or queue handlers change.

The second version saves time because the agent does not need to guess.

The Review Payoff

A repo instruction file does not make an agent perfect. It makes reviews smaller. The reviewer can ask, "Did it follow the contract?" instead of reverse-engineering every decision.

For small teams, that matters more than a fancy agent stack. You get fewer surprise edits, clearer test reports, and a cleaner handoff between human and tool.

The file also helps new developers. The same map that guides an agent helps a new engineer understand where the boundaries are.

What To Avoid

Do not put broad philosophy in the file. Do not add long motivational sections. Do not include secrets. Do not make the file so long the important rules disappear.

The best version is boring:

• exact commands


• exact paths


• exact ownership


• exact test gates


• exact escalation rules

Add A Change Report Contract

The most useful final section tells the agent how to report work back to the reviewer. This is where many teams lose time. The agent makes a reasonable change, but the summary hides the operational detail the reviewer needs.

Add a required handoff format:

## Final Response Format

- Files changed

- Tests run

- Tests not run and why

- Runtime or config impact

- Migration or data impact

- Rollback notes

That format is especially useful in repositories with Docker images, Kubernetes manifests, queue workers, and database migrations. It forces the agent to separate "code changed" from "system behavior changed."

Keep It Close To The Code

Do not bury these instructions in a Notion page or chat thread. Keep them in the repository. Review them like code. When the deployment flow changes, update the instruction file in the same pull request.

This also helps with onboarding. New developers can read the same operating manual as the agent. That creates a shared baseline: commands, boundaries, deployment assumptions, and the definition of done.

A Weekly Maintenance Habit

Once a week, check whether the file is still true.

Look for drift:

• a test command changed


• a new service was added


• the Compose file was renamed


• the deployment moved from one namespace to another


• a generated directory changed


• a migration rule became stricter

Instruction drift is dangerous because it creates confidence without accuracy. A wrong instruction file is worse than no instruction file because the agent will follow it with conviction.

How This Saves Money

This is not only about code quality. It is also cost control. Every confused agent run burns review time. Every unnecessary rebuild burns CI minutes. Every wrong Kubernetes edit risks cloud spend or availability. A small instruction file reduces that waste without buying another platform.

For small teams, that is the practical win: better automation from the tools already available.

Service CTA

TechSaaS helps teams build practical AI-assisted engineering workflows around Docker, Kubernetes, CI, and self-hosted infrastructure. If you want the workflow without the review churn, start here: https://techsaas.cloud/services