{"slug": "the-ai-coding-harness-i-reuse-on-every-project-4-files-skills", "title": "The AI Coding Harness I Reuse on Every Project (4 Files + Skills)", "summary": "A developer who has built AI and AI-native software, including work with frontier models such as Claude Opus, published a reusable four-file Markdown harness — AGENTS.md, SESSION.md, CHECKLIST.md, and HANDOFF.md — that gives coding agents persistent instructions, memory, and skills across sessions. The setup, which takes about five minutes and works with Claude Code, OpenCode, or other coding agents, centers on SESSION.md, which records every meaningful change, findings, issues, verification results, and the next action so work survives between sessions. The author recommends instructing agents to read SESSION.md and CHECKLIST.md before coding, update SESSION.md after each meaningful change, and prepare a handoff if work remains.", "body_md": "You spend an hour with an AI coding agent. It fixes the bug, refactors the module, and finds the real cause of the failing test.\n\nThe next morning you open a new session and it knows none of it. It repeats the same dead end. It undoes a decision you made yesterday. You explain the project again from scratch.\n\nThe model isn’t the problem. The agent has nowhere to keep its work.\n\nSo before I ask any agent to build a feature, I give it a place to keep it. Call it a harness: the instructions, memory, and skills wrapped around the model so its work survives between sessions. Mine is four plain Markdown files:\n\n**AGENTS.md,** **SESSION.md,** **CHECKLIST.md, and** **HANDOFF.md.**\n\nThe most important one is **SESSION.md**. It works whether you use Claude Code, OpenCode, or another coding agent, and it takes about five minutes to set up.\n\nI came to this after years of building AI and AI-native software, including scalable services and systems. Working with frontier models such as Claude Opus taught me what an agent needs to record: what changed, what it learned, which issues are still open, and what the next agent needs to continue.\n\nThese files hold the project’s instructions and working state. Skills supply reusable procedures for planning, debugging, design, and verification. Together they give me a setup I can carry from project to project.\n\nThis is where I put instructions that should outlive the current task:\n\nFor 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?\n\nA useful instruction to include is:\n\n*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.*\n\n**Use it for:** any repository you expect to revisit. Keep it short enough to read at the start of a session.\n\nI want the reasoning and current state to stay with the project, not disappear when the chat closes.\n\nMy 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.\n\nThis is the structure I recommend:\n\n```\n# Session\n## Current objectiveThe outcome we are working toward now.\n## ChangesWhat changed, where, and why. Keep concise dated entries.\n## Findings and decisionsWhat we learned, the evidence, and the decision it informed.\n## Issues and review listOpen, resolved, or blocked issues; what still needs review.\n## VerificationChecks actually run and their results. Mark unrun checks clearly.\n## Next actionThe next concrete step and any blocker.\n```\n\nFor 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.\n\nKeep the current objective and next action easy to find. Older entries can move to an archive as the log grows.\n\n**Use it for:** debugging, refactoring, research, service development, and anything that spans sessions. For a tiny task, a few lines are enough.\n\nA checklist turns “build the MVP” into something you can review.\n\nEach item needs an outcome and a way to confirm it. Here is an example for a document-processing app:\n\n```\n# MVP deliverables\n- [ ] 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.\n```\n\nCreating 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.\n\n**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.\n\nWhen I switch agents or pass work to a reviewer, I need a clear starting point.\n\nMy handoff includes:\n\nAn 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.”\n\n**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.\n\nThe four files are the foundation. Add skills according to the work in front of you.\n\n**Small script or focused bug fix:** Short instructions, a session note, and a completion checklist. Extra packs are optional.\n\n**Backend API or service:** The four-file structure plus one development workflow pack.\n\n**MVP with a user interface:** Add Frontend Design and Webapp Testing.\n\n**Dataset, model, or evaluation work:** Add the relevant Hugging Face skills.\n\n**Building an MCP server:** Add MCP Builder.\n\n**Long investigation or refactor:** Keep SESSION.md current. Add Planning with Files if its workflow helps manage the task.\n\n**Repeating your own engineering procedure:** Package that procedure with Skill Creator.\n\nHere is how I put those choices to work.\n\nI use [Superpowers](https://github.com/obra/superpowers) for structured planning, debugging, testing, and review. [Matt Pocock’s skills](https://github.com/mattpocock/skills) are useful for clarifying a change and documenting decisions; the collection’s grill-with-docs workflow fits that preparation.\n\nFor an unclear feature, start with this instruction:\n\n*Clarify the expected behavior and failure cases. Record decisions in SESSION.md and turn the agreed scope into CHECKLIST.md before implementation.*\n\nPick 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.\n\nI use [Frontend Design](https://github.com/anthropics/skills/tree/main/skills/frontend-design) to guide the interface and [Webapp Testing](https://github.com/anthropics/skills/tree/main/skills/webapp-testing) to inspect the local app with browser checks.\n\nGive 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.\n\n[Hugging Face Skills](https://github.com/huggingface/skills) help with dataset, model, evaluation, and Hub workflows.\n\nI 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.\n\nI use [MCP Builder](https://github.com/anthropics/skills/tree/main/skills/mcp-builder) when exposing a service through an MCP server.\n\nStart 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.\n\n[Planning with Files](https://github.com/OthmanAdi/planning-with-files) provides persistent planning, findings, and progress workflows.\n\nIt 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.\n\nI use [Skill Creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator) to make a recurring procedure reusable.\n\nA 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.\n\nCopy this and fill in the brackets:\n\n```\nBuild 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].\nInspect the repository first. Preserve existing instructions and work.Create or update these files before implementation:\nAGENTS.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.\nUse the available skills relevant to this project: [selected skills].If a requested skill is unavailable, say so and continue with aclear plan. Ask about missing information only when it blocks work.Record other assumptions in SESSION.md.\nBuild the smallest complete user journey first. After each meaningfulchange or investigation, update SESSION.md. Verify deliverables withappropriate checks; only mark checklist items complete with evidence.Finish with run instructions, known gaps, and an updated handoff.\n```\n\nOne 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.\n\nOn 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.\n\nYes, with a few checks.\n\n[OpenCode supports AGENTS.md](https://opencode.ai/docs/rules/). [Current Claude Code supports it too](https://code.claude.com/docs/en/memory), 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.\n\nThe other three files are ordinary project documents. The prompt and AGENTS.md tell the agent to read and maintain them.\n\nBoth tools support skill files, including project skills under .claude/skills/; see the [Claude Code](https://code.claude.com/docs/en/skills) and [OpenCode](https://opencode.ai/docs/skills/) 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.\n\nFor your first project, start with a clear deliverable and a useful SESSION.md. Add the skill that helps with your next task.\n\nWhen 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.\n\n[The AI Coding Harness I Reuse on Every Project (4 Files + Skills)](https://pub.towardsai.net/the-ai-coding-harness-i-reuse-on-every-project-4-files-skills-936cdd492c3e) was originally published in [Towards AI](https://pub.towardsai.net) on Medium, where people are continuing the conversation by highlighting and responding to this story.", "url": "https://wpnews.pro/news/the-ai-coding-harness-i-reuse-on-every-project-4-files-skills", "canonical_source": "https://pub.towardsai.net/the-ai-coding-harness-i-reuse-on-every-project-4-files-skills-936cdd492c3e?source=rss----98111c9905da---4", "published_at": "2026-10-03 12:39:13+00:00", "updated_at": "2026-10-03 13:07:31.456904+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-products"], "entities": ["Claude Code", "OpenCode", "Claude Opus"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/the-ai-coding-harness-i-reuse-on-every-project-4-files-skills", "markdown": "https://wpnews.pro/news/the-ai-coding-harness-i-reuse-on-every-project-4-files-skills.md", "text": "https://wpnews.pro/news/the-ai-coding-harness-i-reuse-on-every-project-4-files-skills.txt", "jsonld": "https://wpnews.pro/news/the-ai-coding-harness-i-reuse-on-every-project-4-files-skills.jsonld"}}