ARTICLE

The AI Coding Harness I Reuse on Every Project (4 Files + Skills)

How I set up Claude Code and OpenCode before writing any code: 4 Markdown files plus the right skills. Copy the prompt, ship your MVP.

1. AGENTS.md: how I want the agent to work

This is where I put instructions that should outlive the current task:

What the project does and how the code is organized.
Commands to run, build, and verify it.
Engineering conventions and important constraints.
When to read and update the other three files.

For a Python service, I include the boundaries between API handlers, business logic, and external services. I also make failure behavior explicit: what happens when a dependency times out, a request is invalid, or a background job fails?

A useful instruction to include is:

Before coding, read SESSION.md and CHECKLIST.md. After each meaningful change or investigation, update SESSION.md. Before finishing, review the checklist and prepare a handoff if work remains.

Use it for: any repository you expect to revisit. Keep it short enough to read at the start of a session.

2. SESSION.md: the file that stops the forgetting

I want the reasoning and current state to stay with the project, not disappear when the chat closes.

My session file captures every meaningful change, its summary, findings, issues, and the review list. An unsuccessful investigation belongs here too, because the next agent needs to know what was already tried.

This is the structure I recommend:

# Session

## Current objective
The outcome we are working toward now.

## Changes
What changed, where, and why. Keep concise dated entries.

## Findings and decisions
What we learned, the evidence, and the decision it informed.

## Issues and review list
Open, resolved, or blocked issues; what still needs review.

## Verification
Checks actually run and their results. Mark unrun checks clearly.

## Next action
The next concrete step and any blocker.

For a document-processing MVP, an entry such as "fixed parsing" gives the next agent very little to work with. Record the failing input, the relevant parser, the change, and the check that confirmed it.

Keep the current objective and next action easy to find. Older entries can move to an archive as the log grows.

Use it for: debugging, refactoring, research, service development, and anything that spans sessions. For a tiny task, a few lines are enough.

3. CHECKLIST.md: what "done" means

A checklist turns "build the MVP" into something you can review.

Each item needs an outcome and a way to confirm it. Here is an example for a document-processing app:

# MVP deliverables

- [ ] Accept a supported document upload.
- [ ] Show extracted fields in an editable view.
- [ ] Explain unsupported-file and processing errors.
- [ ] Save a user's corrections.
- [ ] Verify the upload-to-result flow with a sample document.
- [ ] Document local setup and known limitations.

Creating a route or a component does not complete an item by itself. I want evidence that the intended behavior works. A blocked item stays visible with its reason.

Use it for: MVPs, releases, client work, and features with several deliverables. For a bug fix, it can be just the reproduction, the fix, and a regression check.

4. HANDOFF.md: how any agent picks up the work

When I switch agents or pass work to a reviewer, I need a clear starting point.

My handoff includes:

The objective and current state.
Relevant files and decisions, with references to SESSION.md.
Remaining issues and verification gaps.
The next action and how to check its result.

An example handoff could say: "Upload validation is implemented. The browser flow still needs review. Start with the upload component, reproduce the unsupported-file case, and record the result in SESSION.md."

Use it for: another agent, another developer, a review, or a session you will resume later. Refresh it when transferring work; a short task completed in one sitting may not need it.

Which skills to add for which project

The four files are the foundation. Add skills according to the work in front of you.

Small script or focused bug fix: Short instructions, a session note, and a completion checklist. Extra packs are optional.

Backend API or service: The four-file structure plus one development workflow pack.

MVP with a user interface: Add Frontend Design and Webapp Testing.

Dataset, model, or evaluation work: Add the relevant Hugging Face skills.

Building an MCP server: Add MCP Builder.

Long investigation or refactor: Keep SESSION.md current. Add Planning with Files if its workflow helps manage the task.

Repeating your own engineering procedure: Package that procedure with Skill Creator.

Here is how I put those choices to work.

Backend work: choose one development workflow

I use Superpowers for structured planning, debugging, testing, and review. Matt Pocock's skills are useful for clarifying a change and documenting decisions; the collection's grill-with-docs workflow fits that preparation.

For an unclear feature, start with this instruction:

Clarify the expected behavior and failure cases. Record decisions in SESSION.md and turn the agreed scope into CHECKLIST.md before implementation.

Pick one workflow to lead the task. For a backend-only MVP, this is where I start; design and ML packs can wait until the project needs them.

UI work: design it, then verify the interaction

I use Frontend Design to guide the interface and Webapp Testing to inspect the local app with browser checks.

Give the agent the main user journey: upload a document, correct a field, save it. Ask it to record screenshots, observed failures, and verification results against the checklist. Browser testing needs the required Playwright environment.

ML work: add only the relevant Hugging Face skills

Hugging Face Skills help with dataset, model, evaluation, and Hub workflows.

I define the evaluation question first. For retrieval, that means deciding what a useful result looks like and which failure cases matter. Then I ask the agent to record dataset assumptions, commands, results, and unresolved findings in SESSION.md.

Agent tools: use MCP Builder when building the integration

I use MCP Builder when exposing a service through an MCP server.

Start with the tool's job, inputs, outputs, and failure behavior. Put the implementation and verification requirements in the checklist. The server and its connection still need to be configured and tested.

Longer work: give planning files one clear role

Planning with Files provides persistent planning, findings, and progress workflows.

It uses its own file conventions. If I add it, I decide which file owns each piece of state and link the records. Two competing progress logs make a handoff harder. My four-file setup already works without this pack; I add it when its workflow is useful.

Repeated work: turn your procedure into a skill

I use Skill Creator to make a recurring procedure reusable.

A focused service-review skill could check validation, async behavior, timeouts, and dependency failures. Keep project-specific details in AGENTS.md and SESSION.md, so the procedure can travel to another repository.

The one prompt that starts your MVP

Copy this and fill in the brackets:

Build an MVP for [product] that helps [user] achieve [main outcome].
Use [stack]. The essential user journey is [steps].
For this version, exclude [out-of-scope features].

Inspect the repository first. Preserve existing instructions and work.
Create or update these files before implementation:

AGENTS.md — project structure, commands, conventions, and workflow.
SESSION.md — objective, change summaries, findings, decisions,
             every issue and its status, review list, verification,
             and next action.
CHECKLIST.md — MVP deliverables with acceptance criteria.
HANDOFF.md — current state, relevant files, remaining work,
             and instructions for the next agent.

Use the available skills relevant to this project: [selected skills].
If a requested skill is unavailable, say so and continue with a
clear plan. Ask about missing information only when it blocks work.
Record other assumptions in SESSION.md.

Build the smallest complete user journey first. After each meaningful
change or investigation, update SESSION.md. Verify deliverables with
appropriate checks; only mark checklist items complete with evidence.
Finish with run instructions, known gaps, and an updated handoff.

One prompt can start the build and set up the workflow. A working MVP still depends on a manageable scope, the environment, and checking the result. I keep reviewing and refining as the work develops.

On the next project, reuse the structure and the relevant skills. Reset the session, checklist, and handoff, and adapt the project instructions. Old project state should not become the new project's context.

Does this work in Claude Code and OpenCode?

Yes, with a few checks.

OpenCode supports AGENTS.md. Current Claude Code supports it too, with version and configuration conditions. If Claude Code is loading CLAUDE.md instead, its documented @AGENTS.md import lets you share the instructions. Confirm which file your agent actually loads.

The other three files are ordinary project documents. The prompt and AGENTS.md tell the agent to read and maintain them.

Both tools support skill files, including project skills under .claude/skills/; see the Claude Code and OpenCode documentation. Keep companion resources with a skill and follow each pack's installation instructions for your agent. Reusing the files does not guarantee that every plugin or runtime dependency transfers automatically.

Start tomorrow's session where today's ended

For your first project, start with a clear deliverable and a useful SESSION.md. Add the skill that helps with your next task.

When you come back tomorrow, or hand the work to another agent, you should be able to see what happened and continue from there. That is the whole point of the four files.

More writing

How to Use, Optimize, and Serve an LLM in Your Production System