The Agentic Project Harness
A baseline operating layer for agent-friendly repositories — four readiness levels from context harness to product harness.
Every repo an AI agent touches needs a harness: the operating layer around the product — instructions, checks, scripts, docs, runbooks. Its job is to make the repo legible enough that humans and agents can change it safely without relying on context that lives in someone's head. If a repo needs hidden memory to be changed safely, the harness is incomplete.
Ground truth is disk, not memory.
The harness builds up in four levels. Each one adds what matters at that stage.
L0: Context harness
Make the repo legible.
| Item | Purpose |
|---|---|
| Agent instructions (AGENTS.md / CLAUDE.md) | Repo-specific behavior, guardrails, commands, and forbidden actions |
| README | Fast entry point for humans |
| Skills | Repeatable workflows the agent should follow |
| MCP configs | Structured access to external tools |
| Docs folder | Durable product, architecture, and operational context |
| Scratch-pad | A named space for temporary investigation notes |
| Scripts folder | Repeatable operational commands |
| Decision records | Why the important choices were made |
L1: Development harness
Make local development repeatable.
.env.example— required env vars without leaking secrets.gitignore/.dockerignore— noise and secrets stay out of git and Docker- A one-command local bootstrap
- Linting, formatting, type checks, tests
- Pre-commit hooks — cheap checks earlier than CI
- Automated migrations
- A changelog folder
- Dependency management
L2: Production harness
Required before production traffic, sensitive data, payments, or customer commitments.
- CI/CD with gated deploys
- Health checks and monitoring
- Database backup and restore drills
- Alerting and runbooks
- Secrets management
- Security and dependency scanning
- Performance testing
- Incident history
L3: Product harness
Adopt when stage, team size, compliance, or growth motion justifies it.
- User feedback collection and analysis
- License and legal documentation
- Feature flags and experimentation
- Customer support and issue tracking
- Marketing and outreach
Repo shape
.
├── AGENTS.md or CLAUDE.md
├── README.md
├── .env.example
├── .gitignore
├── .dockerignore
├── docs/
├── scripts/
├── changelog/
├── scratch-pad/
├── infra/
├── migrations/
├── tests/
└── .github/workflows/
Folder names matter less than discoverability. A new maintainer or agent should find instructions, commands, docs, verification, release history, and runbooks within minutes.
Completion discipline
Before any agent claims work is done:
- Recover state from disk.
git statusandgit diffshow the actual changes, not memory. - Inspect. Edge cases, stale assumptions, missing tests, state leakage, docs drift.
- Verify. Run the completion-check script. Fix issues before the final response.
- Report. Files changed, checks run, remaining risk.
A small completion_check.sh is enough: dirty files, untracked files, conflict markers, debug/TODO markers, large uncommitted blobs. Wire it into git hooks later.
When context is tight, scale the pass down but don't skip it. Priority order: money/payment state, auth/privacy, deploy risk, data correctness, runtime state, user-facing UX, docs/tests.
Each item in the harness is either required for every serious repo, required before production traffic, or project-dependent — adopted only when stage, team size, or compliance asks for it. That's what keeps the harness proportionate to actual risk rather than applying everything everywhere.