The Document Set to Fix Before Delegating Work to an AI Agent

This article is the final part of the “Coding agent runtime Design” series. The previous article covered runtime perspective, Goal Contract, A2A and MCP, AI Memory and run ledger.

This time we transfer theory to a set of actual development harness documents. The goal is simple. Even if the team does not create a huge agent runtime right away, the boundaries and output of the work to be assigned to the agent must be fixed in a file.

To ensure that AI agents can work safely for long periods of time, work contracts and output contracts are separated into files.

Key takeaways

• There is no need to create a huge agent runtime from scratch.
• Starting with an MVP as a document-based harness is sufficient.
• The minimum document set isgoal.md,run-ledger.md,artifact-contract.md,memory-policy.md,permission-policy.md.
• These documents tell the agent not only what to do, but also where to stop and what to leave behind.
• If needed later, this document structure can be promoted to SQLite or runtime state.

Why start with a document set

When creating a development harness, it can be tempting to create a complex system from scratch.

Copy1SQLite state2agent scheduler3multi-agent orchestrator4task queue5memory graph6vector database7permission engine

A structure like this may be needed at some point. But it's too heavy at the MVP stage. Initially, a set of file-based documents will suffice.

OpenAI's [Codex harness article] (https://openai.com/index/unlocking-the-codex-harness/) explains that multiple Codex surfaces share an agent loop through the same harness and App Server. Even if you do not implement App Server yourself, concepts such as agent loop, thread state, approval, and diff event can be absorbed into operational documents.

Recommended directory structure

The MVP structure can start like this:

Copy1.agent-runtime/2goals/3profile-update/4goal.md5plan.md6run-ledger.md7artifacts/8changed-files.md9test-result.md10risk-summary.md11policies/12artifact-contract.md13memory-policy.md14permission-policy.md15memory/16candidates/17validated/

The key is separation. Dividing document sets into roles ensures that agents don't mix goals, execution history, deliverables, and policies in the same language.

Document-based harness

Goals and Action

goal.md: What to finish

run-ledger.md: What it actually did

deliverable contract

artifact-contract.md: What to leave behind

operating policy

memory-policy.md: What to remember

permission-policy.md: What to block

goal.md template

The first file is a contract that ties together the goals, scope, completion conditions, and stop conditions in one place.

Copy1Goal:2Metadata:3goal_id:4created_at:5owner:6status: draft | in_progress | blocked | completed | cancelled7 8Objective:9Write the final goal of this goal in one sentence.10 11Context:12Explain why this work is necessary and what the current status is.13 14Scope:15In Scope:16- Tasks to include17Out of Scope:18- Tasks to exclude19 20Done Criteria:21- Observable completion conditions22- Test or verification commands23- Completion criteria from the user's perspective24- Summary criteria to be left at the end25 26Stop Conditions:27- Stop when DB schema change is required28- Stop when authentication/authorization logic changes are required29- Suspension when external costs occur30- Stop when secret access is required31- Stop production deployment when necessary32 33artifact contract:34- List of changed files35- Summary of key changes36- Verification command executed37- Failed verification and reasons38- Remaining risks39 40Notes:41- Additional notes

This file should be read first by the agent. Long-term execution without goals and stopping conditions carries significant operational risk.

run-ledger.md template

The second file records the agent's actual execution history in task attempt units.

Copy1run ledger Entry:2task_id:3attempt_id:4started_at:5 6input:7- Referenced files8- Documents referenced9- Command executed10 11action:12- Changes made13- Tests run14- What we reviewed15 16result: success | failed | blocked | input_required17 18evidence:19- diff20- test log21- error message22- screenshot23- command output24 25diagnosis:26Interpretation of failure or outcome27 28next_action:29Next direction to try30 31artifact_created:32- Artifact file path33 34memory_decision: none | candidate | validated35human_review_required: yes | no

The run ledger is an agent's work log. You should be able to know what was done without having to look at the conversation log.

artifact-contract.md template

The third file is the baseline that anchors the results of your work as reviewable deliverables rather than conversational responses.

Copy1artifact contract:2Implementation Artifact:3- List of changed files4- Core changes5- Verification command executed6- Passed verification7- failed verification8- Remaining risks9- Parts that need to be checked by humans10 11Test Artifact:12- Added tests13- modified tests14- Command executed15- Pass/Fail result16- How to reproduce failure17- flaky potential18 19Review Artifact:20result_levels:21- blocker22- warning23- suggestion24- verified25- not_verified26 27Failure Artifact:28- failed approach29- Cause of failure30- Evidence log31- Abandoned Home32- Suggest next attempt33- Whether to promote memory

The artifact contract is not a document that tells you to write a nice final response. It is a contract to leave results that can be reviewed.

memory-policy.md template

The fourth file is a filter that determines what to keep as a premise for the next task and what to discard.

Copy1memory policy:2Store:3- Build/test commands required repeatedly4- Important conventions in code base structure5- Coupling, where multiple files must be changed together6- Debugging insight repeated more than once7- Workaround verified in current branch8 9Do Not Store:10- One-time error11- Personal information12- API key, token, secret13- unverified guesses14- Temporary state that exists only in a specific branch15- User's temporary request16 17Validate Before Use:18- Does the referenced file exist in the current branch?19- Doesn’t it conflict with package.json, README, and CI config?20- Has old memory been re-verified?21- Does the scope of application match the current task?22 23Memory Metadata:24- source25- scope26- validated_at27- expires_at28- owner

The reason why [GitHub Copilot Memory document] (https://docs.github.com/en/copilot/concepts/agents/copilot-memory) emphasizes citation, current branch verification, and stale memory deletion is in the same context. Memory is a prerequisite for the next operation, so verification and expiration are required.

permission-policy.md template

The final file is the control surface that divides what the agent can do directly and what needs human approval.

Copy1Permission Policy:2Allowed Without Approval:3- read source files4- edit non-sensitive source files5- run unit tests6- run lint7- run typecheck8- inspect git diff9 10Approval Required:11- add dependency12- modify DB migration13- change auth logic14- change payment logic15- modify CI/CD workflow16- call external paid API17- run e2e test against external service18- update production-like config19 20Blocked:21- read env files22- print secrets23- access production DB24- deploy to production25- run destructive command26- delete user data27- bypass tests

The important thing here is that permission policy is different from instruction. Instruction tells the agent to act like this. Permission is actually a layer that prevents this.

This is the same reason why Claude Code memory document explains memory as context. Security and permissions must be handled in separate policy and enforcement layers.

MVP operation flow

Just creating a document set is not effective. You must fix the order in which files the agent will read and update before starting the job, during execution, and after completion.

1. 01PRD / SPEC / UI
2. 02Create goal.md
3. 03Write plan.md
4. 04Human checking of plans and stopping conditions
5. 05Task unit execution
6. 06run-ledger.md record
7. 07Save artifacts
8. 08memory candidate review
9. 09Generate summary artifact

The advantage of this flow is simplicity. Even if it fails, it can be traced. What's left is where the agent got it wrong, what assumptions it abandoned, what tests it ran, and what to remember for the next task.

expansion direction

Once your file-based MVP is stable, you can expand to the next level.

There is no need to create V5 from scratch. The most important thing is the structure in which the units of work remain.

Copy1If you work without a goal, you lose direction.2If you work without run ledger, you will repeat failure.3If you work without Artifact, you cannot review it.4Working without a memory policy will pollute your memory.5Working without a permission policy becomes dangerous.

final checklist

Before applying the harness to an actual project, the items below should be considered the minimum operating standards.

Copy1[ ] PRD / SPEC / UI documents are prepared.2[ ] Goal.md contains Objective and Done Criteria.3[ ] Stop Conditions include hazardous operations.4[ ] Task attempt is recorded in run-ledger.md.5[ ] There is artifact-contract.md.6[ ] Test results and failure logs remain as artifacts.7[ ] There is memory-policy.md.8[ ] There are standards for memory promotion.9[ ] There is permission-policy.md.10[ ] Secret, production, and deploy operations are blocked.11[ ] There is a flow of human final approval.

finish

Coding agents are becoming more and more powerful. However, to safely use powerful agents, you must design the runtime before the model.

The prompt is the starting point. But product development doesn't stop with prompts. What's important going forward is defining goals, recording tasks, isolating deliverables, verifying memories, and controlling authority.

This is what a development harness is supposed to do.

The takeaway from this series is simple. Separatinggoal.md,run-ledger.md,artifact-contract.md,memory-policy.md, andpermission-policy.mdallows you to treat the agents' tasks as reviewable units of operations rather than as conversations.

Continue reading the series

• Part 1: Why are coding agents runtime?
• Part 2: Goal-based development through Codex/goal
• Part 3: Multi-agent development workflow from A2A and MCP perspective
• Part 4: AI Memory is not RAG
• Part 5: AI Coding Agent Document Set for Application to Development Harness

References

• Unlocking the Codex harness: how we built the App Server
• About agentic memory for GitHub Copilot
• How Claude remembers your project

Practical example: Closing small tasks with a set of documents

There is no need to write all four documents at length just for small feature modifications. However, the role of each document must be maintained. For example, if you are fixing a search ranking bug, write the symptoms and completion criteria ingoal.md, and leave the confirmed commands and results inrun-ledger.md. Inartifact-contract.md, files that need to be changed and generated output are written down, and inmemory-policy.md, it is determined whether this failure is a rule to be reused in the next task.

A failure would be to leave only the QA results and not record why that verification was selected. When the next person takes over the same task, they have to guess again whether they only need to look atnpm run testor whether they needcontent:checkas well. Harness documentation is not a device to increase document volume, but rather a device to reduce guesswork during handover.

The comparison criteria are simple. Decisions left only in conversations fade over the longer the session, and agreements left on file can be reread on the next run. The harness document is not a device to make the agent run longer, but a device to make it clear when to stop and when to take over.