Setting Up a Repository So an AI Coding Agent Can Work in It

A coding agent is only as effective as the feedback your repository gives it. If it can install dependencies, run the tests, run the linter and read a clear README without help, it will usually find its own mistakes. If setup needs tribal knowledge, the agent will guess. A little preparation turns an average agent session into a good one, and it helps human newcomers too.

1. Make setup and verification one command each

The agent should never need to ask how to run something. Put the standard commands in one place. In a JavaScript project that is the scripts section of package.json:

{
  "scripts": {
    "dev": "node src/server.js",
    "test": "node --test",
    "lint": "eslint .",
    "typecheck": "tsc --noEmit",
    "check": "npm run lint && npm run typecheck && npm test"
  }
}

A single check command gives the agent one thing to run before it says "done". Other ecosystems have equivalents: a Makefile, justfile, tox or pyproject.toml scripts.

.PHONY: setup test lint check

setup:
	python -m venv .venv && .venv/bin/pip install -r requirements.txt

test:
	.venv/bin/pytest -q

lint:
	.venv/bin/ruff check .

check: lint test

2. Keep tests fast and deterministic

An agent may run tests dozens of times in a session. If the suite takes ten minutes, it will skip it or wait forever. Make it possible to run a single file or test by name, and document how. Remove tests that depend on the network, the clock or random order, because flaky results send the agent chasing bugs that are not there.

3. Turn on static checks

Type checkers and linters give precise, machine-readable feedback: "line 42, argument of type string is not assignable to number". Models are good at fixing exactly this kind of error. Enable the strictest settings your team can live with, and make sure they run from the command line, not only inside an editor.

4. Write a README that answers the basics

The agent reads your README early. Cover these in plain language:

• What the project does in two sentences.
• How to install, run and test it.
• The top-level folder layout.
• Required environment variables, by name only, never real values.
• Anything surprising: generated files, required services, unusual build steps.

5. Keep the structure predictable

Consistent naming helps the agent guess where code lives. If tests sit next to source files in one module and in a separate folder in another, the agent will mimic whichever it saw last. Pick one convention. Keep generated files, build output and vendored code in clearly named folders so you can exclude them later (see the post on ignore files).

6. Protect the things an agent should not touch

• Keep real secrets out of the repository and out of files in the working directory. Use a .env.example with placeholder names.
• Make sure the main branch is protected so changes arrive through pull requests.
• Work on a branch or a separate worktree, never directly on main.

7. Add a project instruction file

Once the commands exist, record them in the file your tool reads at startup. For Claude Code that is CLAUDE.md. A first version can be very short:

# Project notes

## Commands
- Install: npm install
- Run all checks: npm run check
- Run one test file: node --test test/users.test.js

## Layout
- src/ application code
- test/ tests, one file per module

The next posts explain instruction files in depth.

A readiness checklist

1. A fresh clone can be set up with documented commands.
2. One command runs lint, types and tests.
3. The default test run finishes in a few minutes at most.
4. Tests do not need production credentials.
5. The README matches reality.
6. Secrets are not in the working tree.
7. You can run a single test quickly.

If you can tick all seven, an agent can verify its own work, and your reviews get shorter because obvious failures never reach you.