My Claude Code Setup for Faster Development

I used Claude Code for most of this rebuild. Of the 50 merged pull requests, 46 came from Claude Code branches and four from Codex.

My CLAUDE.md is only three lines long. Those lines load the project instructions, current notes and past mistakes. The rest of the setup adds skills for repeated tasks, checks that run automatically and separate working folders when I need more than one session.

Here are the files I use and how they fit into a normal development task. You can copy them from the public repo and adapt them to your project.

What should Claude read before it starts?

I keep a CLAUDE.md file in the project root. It points to the files that explain how to work on the project. My version contains just these three lines:

@AGENTS.md
@STATE.md
@RULES.md

The @ tells Claude Code to read another file. AGENTS.md holds the project instructions. STATE.md says what was last checked. RULES.md records mistakes I want to avoid. Claude Code supports these file imports.

This gives a new session a starting point. I can ask it to fix a bug without pasting the same project explanation again. I still write the task clearly. The files explain the project; the prompt explains what I need now.

I have put the files at https://github.com/eagerminds-ai/claude-code-harness. The code examples in this post are short extracts from those files or the original project. I removed private details. Some example values are placeholders that you need to replace.

Start with instructions you can explain. If you copy a large file without reading it, you may also copy rules that do not fit your project. Keep the first version small enough to read from top to bottom.

What should I put in AGENTS.md?

Write down the things you would tell a developer joining your project. Where is the app code? Which package manager does it use? How do you run it? Which files need extra care? What should a completed task include?

Use your existing commands. If the project uses pnpm, say that. If an API change needs a test and a real request, say that too. Clear instructions save the session from guessing.

This is part of the verification section in the original file:

1. A task is **done** when the live behavior was observed: a route curled, a screen loaded, a
   row changed in the database. Tests green is a prerequisite, not the finish line.

In simple terms, run the feature and see what happens. For a login fix, try logging in. For a screen change, open the screen. For saved data, check that the saved value is right. Tests help, but they may not cover the part that broke.

I also tell Claude to check existing code before adding a new helper or library. A new function may already exist under another name. Reading the nearby code first can save both implementation time and review time.

How do I stop a new session from starting over?

I use STATE.md for short notes about the current project. Each note includes a date and the check behind it. Old notes get updated or removed.

Here is one line from the public template. It is an example, not a test result:

- Example: `<health command>` returned HTTP 200 for `<environment>` at `<revision>`. [verified 2026-09-13]

Replace the placeholders with your command, environment and commit. Do not leave the example date on a check you have not run. The useful part is being able to tell what was checked and when.

The state checker can catch missing dates, old dates and some issue-status mistakes. It cannot prove that every sentence is true. If GitHub is unavailable, the public script reports that the check is incomplete.

Keep long discussions somewhere else. I use decision files for choices and a message record for answers. STATE.md points to the information needed now. A list of everything that ever happened becomes hard to trust.

For a longer task, I also save a checkpoint. It records what I am doing, what changed, what passed and what to do next. That makes it easier to continue after a break without asking the same questions again.

How do I stop the same mistake from coming back?

When a mistake repeats, I add it to RULES.md. Each row says what went wrong, how often it happened, what might catch it and what result I should check.

Here is a row from the public version:

| R2 | Green is not done | 13 | `AGENTS.md`; `.github/pull_request_template.md` | Observed behavior and exit code |

The number 13 is the count from my original project. Reset it when you copy the template. Your file should describe your own mistakes.

One example explains this row. Typecheck and 88 unit tests passed while every API route returned a 500 error. The test runner could load imports that failed when the real app ran. Later, lint returned exit code 1 for five days while five pull requests described it as clean.

That changed my completion check. I read the command output and its exit code, then try the affected feature. A message saying everything passed is not enough.

If the same failure can be caught by a script, I would add that check. Writing the instruction again may help, but an automatic check is easier to repeat. Some checks still need a person. The rule file should say that plainly.

Where do the detailed rules go?

I put file-specific instructions in .claude/rules. A rule about tests belongs with test work. A rule about mobile screens belongs with mobile work. This keeps AGENTS.md easier to read.

The top of my public test rule looks like this:

---
paths:
  - "**/*.test.ts"
  - "**/*.test.tsx"
  - "**/*.test.js"
  - "**/__tests__/**"
---

These paths tell Claude Code which files the rule applies to. Rules without a paths section load at startup. The instructions still need to be clear; matching a filename does not make a vague rule useful.

For example, I want test data to look like real input. If a bug came from a missing value, a test that always supplies the value will not catch it. That is a specific instruction Claude can use while writing the test.

The original setup has five rule files covering tests, mobile work, operations, end-to-end checks and project records. You can start with just the one your project needs.

Which tasks should become skills?

A skill is a saved set of instructions for a task you repeat. I use skills when a short prompt would leave out useful steps.

The original project had four: brief, checkpoint, client-delivery and dev-reference. Brief looked for earlier answers. Checkpoint saved the active task. Client-delivery covered the steps around finishing work for the client. Dev-reference listed checks to make before saying a tool or environment was unavailable.

The public version calls the delivery example client-feedback. It is a general template, so it leaves out the private messages and account setup.

Each skill has a SKILL.md file with a name and description. The description helps Claude decide when it is useful. You can also ask for the skill directly. The skills documentation explains both ways to use it.

My brief skill is useful before asking a question that may already have an answer. It searches notes, decisions, issues, mail and documents. Then I read the results. A search match is a pointer to an answer, not the answer itself.

Plugins can add skills and other tools. I would add one for a task I already repeat, then check what it does. Installing a plugin does not show that the right skill ran in a particular session.

Which checks should run automatically?

I use hooks for checks tied to an event, such as starting a session or running a tool. That means I do not have to type the same reminder every time.

This is the state-check part of the public settings file:

{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup|resume",
      "hooks": [{
        "type": "command",
        "command": "bash \"$CLAUDE_PROJECT_DIR\"/scripts/check-state.sh state",
        "timeout": 60
      }]
    }]
  }
}

Copy scripts/check-state.sh and scripts/check-state.py as well. The check uses Bash and Python 3; live GitHub checks need gh. Merge the hook into existing settings so you keep any hooks already there.

SessionStart shows the state check when the session starts or resumes. A failed check here does not stop the whole session. PreToolUse works before a tool call and can deny it. InstructionsLoaded records which instruction files loaded. These events have different jobs. The hook reference explains their behaviour.

The repository also has an AWS region check. A query in the wrong region once returned nothing and was treated as an access problem. The hook checks direct AWS commands, but it does not check every possible shell script. Test the commands you expect it to handle.

What does a useful task look like?

I give Claude a small piece of work with a clear finish. For a screen, I write down its route, the data it needs, the parts it contains and what should happen in loading, empty and error states.

The original project had 49 screen cards. Each card covered seven things: route, data, components, states, test IDs, acceptance criteria and source. That gave the next session more to work with than a title such as build the welcome screen.

Here is the sort of example I would write for a new task: when saving fails, show an error, keep the entered text and let the user retry. It says what the user should see. Claude can then find the affected code and test that result.

I also say what should stay unchanged. A screen task should not quietly change a shared API response. If the agreed API is missing something, the session should write down the change it needs.

The route contract started with 52 keys and later had 56. Changes were possible, but they needed a clear reason. That kept separate sessions from inventing different answers to the same problem.

How do I let more than one session work at once?

I give each writer a separate git worktree. A worktree is another working folder for the same repository. It lets a session work on its own branch without changing the files another session is editing.

Claude Code supports this through claude --worktree. I also give each session a clear area to work in. This was the mobile package instruction:

You may only edit files under `apps/mobile/`. Cross-package needs (contracts, db, tokens) are
change requests in `specs/contract-changes.md`, never edits.

In plain English, finish your part and ask for shared changes instead of making them in someone else's files. I still check the diff before accepting the work. The instruction alone cannot stop every unwanted edit.

Separate source folders are only part of the setup. Sessions can still share dependencies, a database or a port. My early setup shared node_modules through links and caused problems. Hard links also share file contents, so they are not safe copies for tools that change those files.

I would install dependencies separately where they can change, give sessions different ports and agree on test data before starting. Shared decision files also need an owner. Two sessions once chose the same decision number even though they used different worktrees.

Why do I keep the starting instructions short?

Claude needs useful information, but it does not need every old discussion before every task. I once loaded the project instructions together with long task, mistake and decision records. Old information still led to wrong answers.

On 8 September, the project records show starting context dropping from 146,463 tokens to about 4,500 after the files were reorganised. Tokens are the pieces of text the model processes. By the later check, the imports had grown back to about 8,100 tokens.

Those are estimates from the project records, not a speed test. The later figure came from file size divided by four. What matters for this setup is the habit: update current notes instead of adding to them forever.

Detailed instructions can sit near the files they concern. Old decisions can stay in a searchable folder. The starting files should help Claude choose its next action without first reading the whole project history.

Should I run all of this overnight?

I would get the small setup working first. Then I would try one task with a clear finish and check what happened before starting more work.

My four-lane runner ran for one night, 2-3 September. Three lanes built changes and one checked them. It merged 26 issues, logged 63 mobile-lane crashes and was stopped the next morning. Some device checks were deferred, so a merge did not mean every screen had been seen on both platforms.

The separate QA sweep filed 283 issues with 631 screenshots. A cloud handoff reported 163 issues worked and 120 fixed. Those were the session's reported results, not 120 fixes I can claim were all independently proven. The fuller cloud setup scripts were never fully deployed in the original environment.

Remote Control let me follow local sessions from my phone. The runbook used a separate monitoring session and /loop for repeated checks. The saved paste does not reveal the exact prompt, so I cannot reproduce its wording. A phone connection is useful, but the local session still needs to stay running.

These are useful things to add after the basic instructions and checks. More sessions create more work to review.

How would I set this up in my own project?

I would add the parts in this order:

1. Copy the three imports into CLAUDE.md and write the project instructions in AGENTS.md.
2. Replace the STATE.md examples with checks I have actually run.
3. Add one mistake to RULES.md and say how I will catch it next time.
4. Add the state hook, run its script myself and read the result.
5. Move detailed test or mobile instructions into the right rule file.
6. Turn one task I repeat into a skill.
7. Try a second writing session only when its files and checks are clear.

I would then use the setup on one real task. Ask Claude to read the relevant files, explain the change it plans to make, implement it and run the right checks. Read the changed code and try the result.

If something still needs repeating, that tells me which instruction is missing. If a check keeps producing noise, I fix the check. I do not want a long list of warnings that everyone learns to ignore.

The useful measure is whether work gets finished with less repeated explanation and fewer corrections. I have not measured a 10x speed increase. Faster development is the goal; completed, checked work is how I would judge it.

What do the project numbers tell me?

The project recorded 951 commits, 573 issues and 50 merged pull requests. The busiest ten-day stretch accounts for 871 of those commits. The full project period covered 18 calendar days. Four of those pull requests came from Codex branches; the other 46 came from Claude Code. Those numbers describe the work recorded, not a test showing how much faster one person became.

The apps remain on internal testing tracks only. They have not been publicly released, by the client's instruction. The source code, messages and screenshots stay private. The public repository contains the setup files and cleaned examples.

I use the failures in those records to explain why the checks exist. You can copy the approach without copying the whole project or running the same number of agents.

FAQ

Built in the open at github.com/eagerminds-ai/claude-code-harness.