A Minimal Workbench

In plain words

In a group project, the giant guidelines doc goes unread and the real status is lost in a WhatsApp thread. Agents have the same problem. So give the agent three small files instead: a short signboard file that points at everything, a state file saying where it is right now, and a task board holding the queue. Chat disappears, files do not.

How it flows

A tiny example

state = read_json("agent_state.json")
if state["active_task"] is None:
    state["active_task"] = pull_top_todo("task_board.json")

step = think(state)          # one small step only
state["touched"].append(step["file"])
state["next_action"] = step["next"]
write_json("agent_state.json", state)

Notice the turn starts and ends on disk, so a brand new session with zero chat history can continue from exactly the same place.

What you will learn

• The three files that make the smallest useful agent workbench.
• Why a short instruction file beats a long one.
• How to keep the agent's memory in a file instead of in chat.
• How to run a task board the agent pulls work from.

The problem, simply

Think about your final-year project team. Four people, one shared folder, work spread over three months.

On day one somebody writes a big 20-page "project guidelines" document. Nobody reads it after the first week. Then Rahul asks "what is left to do?" and the answer is buried in a WhatsApp group with 4000 messages. He gives up scrolling and redoes work Priya already finished.

Now replace the four students with an AI agent. Same story. A giant instructions file gets skimmed, and the actual "where are we" information lives in the chat window. The session closes, the chat is gone, the agent starts from zero.

See, the fix is not a bigger document. The fix is to move the important things out of chat and into small files on disk that both you and the agent can read.

The idea

A workbench is the set of files an agent works out of. The smallest useful one is three files, each with exactly one job.

File 1: AGENTS.md, the signboard

AGENTS.md is the root instruction file most coding agents look for. Think of it like the signboard at the entrance of your college: it does not teach you civil engineering, it just says "Library that way, Exam cell this way."

So AGENTS.md should be short and point at four things: where the state file is, where the task board is, where the deeper rules live, and the exact command to check that the work is correct.

Anything long goes into a separate document that gets opened only when needed. Long manuals get ignored. Short signboards get followed.

Warning

Warning: A conflicting instruction file is worse than no file. If one line says "always write tests" and another line says "keep changes minimal, skip tests", the agent stops asking questions and just guesses. One measurement on ambiguous coding tasks saw the success rate fall from about 49% to about 28% when instructions contradicted each other. Number your priorities: 1, 2, 3. Do not stack rules flat.

File 2: agent_state.json, the diary

This file answers one question: where are we right now?

It carries the current task id, which files were touched, what assumptions the agent made, what is blocking it, and what the next action is. The agent reads it before doing anything and writes it back after.

Why a file and not the chat? Because chat dies. Sessions close, long conversations get trimmed, tools get restarted. The file survives all of that.

IMPRemember: the file is the source of truth, not the conversation.

File 3: task_board.json, the queue

This is the backlog. Every task has an id, a goal, an owner, acceptance criteria, and a status: todo, in_progress, done or blocked.

When the state file is empty, the agent pulls the next todo from the board. When you want to know if things are on track, you read the board instead of asking.

Keep it small on purpose. If the board does not fit on one screen, you have a planning problem, not a board problem.

One turn, end to end

Suppose Sneha points an agent at a Django project. The board has task T-2: "add a rate limit on the login route", acceptance is "the login test suite passes".

Turn one: state is empty, so the agent pulls T-2, marks it in_progress, edits views.py, and writes state saying "touched views.py, next action: add the test". Sneha closes her laptop and goes for dinner.

Turn two, next morning, fresh session, zero chat history. The agent reads agent_state.json, sees T-2 in progress and "next action: add the test", and continues from exactly there.

Real repos go a bit further

Big repos put an AGENTS.md in each sub-folder, not just at the root. Tools walk from the file you are editing up to the repo root and join every AGENTS.md they find. The nearest one wins; the sub-folder file extends the root file. OpenAI's main repo ships 88 of these.

And because different tools look for different filenames, teams keep one real file and symlink the rest to it, so CLAUDE.md and the Copilot instructions file all point back to the same AGENTS.md. One source of truth, no forked copies.

Tip

Tip: Put commands first in your AGENTS.md, style rules last. And never write a style rule you cannot enforce with a command. "Follow good style" lets the agent invent its own definition of good.

Build it

This script builds the three files in a fresh folder and runs two agent turns, so you can see the second turn resume the first.

import json, os, tempfile

WORK = tempfile.mkdtemp(prefix="workbench_")
STATE = os.path.join(WORK, "agent_state.json")
BOARD = os.path.join(WORK, "task_board.json")

def write_json(path, data):
    with open(path, "w") as f:
        json.dump(data, f, indent=2)

def read_json(path):
    with open(path) as f:
        return json.load(f)

# File 1: the short router. Note how it only points at things.
with open(os.path.join(WORK, "AGENTS.md"), "w") as f:
    f.write("# Agent rules\n"
            "1. Read agent_state.json first.\n"
            "2. If no active task, pull the top todo from task_board.json.\n"
            "3. Verify with: python3 -m unittest\n")

# File 2: state starts empty. Nothing in flight yet.
write_json(STATE, {"active_task": None, "touched": [], "next_action": None})

# File 3: the queue.
write_json(BOARD, {"tasks": [
    {"id": "T-1", "goal": "add login rate limit", "status": "todo",
     "accept": "login tests pass"},
    {"id": "T-2", "goal": "log failed logins", "status": "todo",
     "accept": "log file has entries"},
]})

def fake_model(state, task):
    """Stands in for a real model. Returns the next small step."""
    if not state["touched"]:
        return {"file": "views.py", "next": "write the test"}
    return {"file": "test_views.py", "next": "done, close the task"}

def turn(n):
    state, board = read_json(STATE), read_json(BOARD)
    if state["active_task"] is None:                 # pull from the board
        todo = next(t for t in board["tasks"] if t["status"] == "todo")
        todo["status"] = "in_progress"
        state["active_task"] = todo["id"]
        write_json(BOARD, board)
    task = next(t for t in board["tasks"] if t["id"] == state["active_task"])
    step = fake_model(state, task)                   # one small step only
    state["touched"].append(step["file"])
    state["next_action"] = step["next"]
    write_json(STATE, state)                         # durable, survives restart
    print("turn", n, "->", state["active_task"], "|", state["touched"],
          "| next:", state["next_action"])

turn(1)
turn(2)   # fresh read from disk, no chat history needed
print("workbench at:", WORK)

Look at the two printed lines. Turn 2 never saw turn 1 in memory; it only read agent_state.json from disk and still continued correctly. Also notice the board changed T-1 to in_progress on turn 1 and turn 2 did not re-pull it. That resume behaviour is the whole point of the workbench.

Where you will see this

• Claude Code reads a root instruction file in your repo and keeps its own state and hooks alongside it.
• Cursor uses workspace rules as the router and the sidebar task list as an informal board.
• GitHub Copilot reads a repository instructions file for the same routing job.
• Any internal "auto-fix the failing build" bot at a company keeps a job state file so a crashed run can be picked up again.
• Customer support agents keep the ticket record in a database, not in the chat. Same idea.

Common mistakes

• Writing a 3000-line instruction file. The model skims it, keeps the parts it can summarise, and quietly drops the rest, so you get less control, not more.
• Keeping state only in the chat window. One closed tab and the agent has no idea what it already did, so it redoes or contradicts its own work.
• Contradicting yourself across rules. The agent stops clarifying and starts guessing, and success rates fall sharply.
• Style rules with no command to check them. The agent will claim it followed the guide, and you have no way to prove otherwise.
• Letting the board grow to hundreds of tasks. Then nobody reads it, and the agent picks whatever is on top, which is rarely the important thing.

If they ask in an interview

Q: What is the minimum setup needed for an agent to work on a real codebase across many sessions?

A: Three files. A short router file at the repo root that points at everything else, a state file the agent reads and writes every turn, and a task board holding the queue with statuses. Everything fancier, like verification gates and reviewer checklists, sits on top of these three.

Q: Why keep agent state in a file instead of in the conversation?

A: Conversations are volatile. Sessions end, long histories get trimmed, and tools restart. A JSON file on disk survives all of that, and it is machine-readable, so the next session or a completely different tool can pick up the work.

Q: How should instructions be organised in a large monorepo?

A: One short file at the root plus one per major sub-folder. Tools walk from the file being edited up to the root and join what they find, with the nearest file taking priority. Keep one real file per location and symlink the other tool-specific filenames to it so there is a single source of truth.

Try these

1. Add a last_run timestamp to the state file. Make the script refuse to run a turn if the state is more than 24 hours old, unless you pass a confirm flag.
2. Add a priority number to each task and change the puller to always take the highest-priority todo instead of the first one.
3. Write a small checker script that fails if your instruction file is longer than 80 lines or mentions a file that does not exist.
4. Look at any project you already have and write its AGENTS.md in under 20 lines. Then ask yourself which of the three files would hurt most to lose, and why.

Words, simply

Quick recap

• Three files are the floor: a short router, a state file, a task board.
• Keep truth on disk, not in chat, because chat disappears and files do not.
• Short and consistent instructions beat long ones; contradictions quietly make the agent worse.