A starter harness for solo developers using a coding agent — Claude Code, Gemini CLI, Codex CLI, or any generic LLM coding assistant — who haven't yet built a portfolio of corrections to bring to it.
The advanced claude-harness-starter (Claude-specific) assumes you've corrected your agent on the same operational mistake twice, that you have opinions ready to encode, and that your IDENTITY.md is waiting to be filled in. This repo is for the moment before that — and it's tooled for any coding agent, not just Claude.
You'll find pieces, a formula, individual parts, and a framework. You'll find opinions — strong ones — clearly labeled as defaults. Override what doesn't fit you. Deviate where your judgment differs. The repo is the mentor; you're the apprentice; your harness is yours.
If the pieces fit, you'll use them. If they don't, you'll discover what fits better — and that discovery is the point. The repo can't graduate you; it can only give you starting material.
The conceptual harness (identity, rules, memory, projects) is the same across every modern coding agent. The mechanics — where files live, what commands inspect them, what the rule-loading conventions are — differ. The four setup paths in setup/ translate the same conceptual harness to each agent's specifics.
| Agent | Setup path | Notes |
|---|---|---|
| Claude Code (Anthropic CLI) | setup/claude.md |
Most mature support; ~/.claude/rules/ auto-discovery, /memory for inspection |
| Gemini CLI (Google) | setup/gemini.md |
Uses GEMINI.md for project context; rule conventions evolving |
| Codex CLI (OpenAI) | setup/codex.md |
Uses AGENTS.md convention; supports per-project + per-user context |
| Other / generic | setup/generic.md |
Any agent that loads a system prompt or supports a context file at session start |
All four setup paths get you to the same place: a working two-layer harness (one rule + one project context file) in about thirty minutes. The exercises, starter rules, and personas in the rest of the repo work regardless of which agent you chose.
You'll get value from this repo if:
- You've used a coding agent for a few sessions and noticed it gets some things wrong for you in particular.
- You don't yet know what your "building philosophy" is, but you sense you have one.
- You want a harness, but a blank-slate scaffold feels like a homework assignment you're not sure how to start.
- You're a solo developer, hobbyist, career-switcher, domain expert who codes, or any shape in between.
Skip this repo if you already have a portfolio of corrections, opinions ready to encode, and a draft identity file in your head. Use claude-harness-starter (if you're on Claude) or its equivalents for other agents.
| Piece | What it is | When you'll touch it |
|---|---|---|
BEGIN_HERE.md |
A first session that gets you a working harness in about 30 minutes. Routes you to the setup path for your agent. | First. Do this before anything else. |
setup/<agent>.md |
Per-agent install specifics — where rule files live, what commands inspect context, what conventions your agent uses. | During BEGIN_HERE.md. |
exercises/ |
Three short sessions that build on each other — first day, first week, first month milestones. Agent-agnostic. | After BEGIN_HERE.md. Spread them out. Sit with each. |
starter-pack/rules/ |
Seven default rule files — opinionated, with explicit "deviate when this doesn't fit you" exits. Written agent-agnostic; setup path tells you where to install them. | Copy what resonates into your agent's rules location. Modify in place when something doesn't fit. |
personas/ |
Four worked examples of filled identity files plus a fifth "AI-augmented" prompt for when none of the four fit. Agent-agnostic. | When you start drafting your own identity. Use them as conversation starters, not templates. |
memory-explainer.md and decision-log-template.md |
What an agent's persistent-memory layer typically does, and a lightweight decision log template. | When you're ready for the persistence layers. |
Every mature coding-agent setup converges on the same four layers, regardless of vendor:
┌─────────────────────┐
│ 1. IDENTITY │ your building philosophy — rarely changes
└──────────┬──────────┘
│ constrains
┌──────────▼──────────┐
│ 2. RULES │ how you operate day to day — occasionally
└──────────┬──────────┘
│ constrains ┌─────────────────────┐
┌──────────▼──────────┐ │ 3. MEMORY │
│ 4. PROJECT context │◄─────────┤ what the agent │
└─────────────────────┘ │ learns across sessions
└─────────────────────┘
| Layer | Conceptually | How fast it changes |
|---|---|---|
| 1. Identity | Your building philosophy. The slowest-moving layer. | Slow. Months to years. |
| 2. Rules | Operational corrections you'd apply across projects. | Occasionally. Edit as you correct your agent on the same thing twice. |
| 3. Memory | What the agent has learned across sessions. Most modern agents auto-manage this. | Constantly. The agent maintains it. |
| 4. Project | Per-project context the agent reads on session start. | Per project. |
The setup path for your agent tells you where each of these layers lives mechanically. The conceptual model is the same everywhere.
This repo is written in second person — "you'll find that…" rather than "the practitioner…" or "I learned that…". That's deliberate. The repo is talking to you, not about you, not at you.
When you read an opinion in a starter rule, treat it the way you'd treat a senior colleague's advice on your first day: assume there's a reason behind it, try it first, and replace it when you find yours doesn't match. A starter rule with no override comment after 30 days of use is a rule you've absorbed. A starter rule you've rewritten is a rule you've made yours. Both outcomes are good.
The repo won't track which you've done. That's not its job. Your harness is yours.
There's no certificate. There's no checkpoint that says you're done. But you'll notice the following:
- Your identity file has axioms you'd defend in an argument, not axioms you copy-pasted from a persona.
- More than half of your rule files have been edited from the starter pack, not adopted unchanged.
- You've corrected your agent on something twice and written a new rule about it without anyone asking you to.
- You have a project context file you actually read mid-session, not one you wrote and forgot.
When that's true, you've outgrown this repo. Move to a more advanced agent-specific scaffold (such as claude-harness-starter for Claude) — its assumptions will match yours.
Or stay. The harness you've built will keep working. The advanced starter is one direction; staying here is another.
- A curriculum. You don't pass or fail. The exercises don't have right answers.
- A philosophy. The starter rules are defaults, not commandments. The personas are shapes, not assignments.
- Vendor-specific. The conceptual harness is portable across Claude Code, Gemini CLI, Codex, and most coming-soon agents. Setup mechanics differ by vendor; conceptual layers don't.
- A finished product. Foundations is v0.1. It will evolve based on what apprentices report back.
- A replacement for using your agent. Use it. Make mistakes. Correct it. Notice your corrections. Foundations is the place to put what you notice — it doesn't generate the noticing for you.
BEGIN_HERE.md. Thirty minutes. You'll have a working harness when you're done with it.
Then exercises/01-frustration-inventory.md for the first day.
The rest of the repo is reference. You'll come back to it when you need it.
MIT. Fork freely. No attribution required. If the pieces fit, the credit is yours; if you deviate, the journey is yours.