DEV Community: Truong Phung

📘 Spec Kit vs. Superpowers ⚡ — A Comprehensive Comparison & Practical Guide to Combining Both 🚀

Truong Phung — Sat, 25 Apr 2026 10:22:45 +0000

A side-by-side look at two of the most influential frameworks for structured, agentic AI coding — plus a step-by-step playbook for using them together:

github/spec-kit — GitHub's toolkit for Spec-Driven Development (SDD).
obra/superpowers — Jesse Vincent's agentic skills framework for disciplined agent-driven development.

Both projects address the same underlying problem — AI coding agents are powerful but unstructured — but they solve it from very different angles. Spec Kit treats the specification as the source of truth; Superpowers treats the development workflow as the source of truth.

📑 Table of Contents

⚡ TL;DR
1. 🧠 Philosophy
2. 🔄 Workflow & Mental Model
3. 🏗️ Architecture & Primary Unit
4. 🤖 Agent / Tool Compatibility
5. 📦 Installation & Distribution
6. 🧩 Customization & Extensibility
7. 🌟 What Each Does Especially Well
8. ⚖️ Tradeoffs & Limitations
9. 🤝 How They Could Coexist
9a. 🛠️ The Best Way to Combine Both — A Practical Guide
- ⚙️ One-time setup
- 🔁 The per-feature loop
- 📜 Two non-obvious rules
- 📋 Handoff prompt template
- 📏 When to scale down
- 🚫 Anti-patterns to avoid
- ✅ 60-second checklist
10. 🧭 Quick Decision Guide
11. 📊 At-a-Glance Summary

⚡ TL;DR

	Spec Kit	Superpowers
Author / Owner	GitHub (org-backed)	Jesse Vincent + Prime Radiant team
Core idea	Specs are executable; code is generated from specs	Skills enforce a disciplined dev workflow
Primary artifact	The specification document	The skill (a triggered procedure)
Trigger model	User-invoked slash commands (`/speckit.*`)	Auto-triggered skills based on context
Methodology	Spec-Driven Development (SDD)	Agentic SDLC (brainstorm → design → plan → TDD → review → ship)
Best for	Greenfield features, brownfield enhancements, spec-to-code traceability	Multi-hour autonomous work, parallel subagents, TDD discipline
Distribution	Python CLI (`uv tool install specify-cli`)	Plugin marketplaces (Claude, Codex, Cursor, etc.)
License	MIT	MIT
Maturity	90.8k stars, 136 releases, 100+ community extensions	167k stars, active releases, Discord community

1. 🧠 Philosophy

📘 Spec Kit — "The spec is the source of truth"

Spec Kit flips the traditional flow: instead of writing code that loosely tracks a spec, the spec directly generates the implementation. Changes happen at the spec layer first; code is regenerated to match. Quoting the README: "specifications become executable, directly generating working implementations rather than just guiding them."

Foundational principles:

Intent first — what & why before how
Rich, guard-railed specifications with organizational principles
Multi-step refinement instead of one-shot generation
AI-native workflows that lean on advanced model capabilities

🦸 Superpowers — "The workflow is the source of truth"

Superpowers prevents agents from immediately jumping into code. It enforces a disciplined sequence: discovery → design validation → planning → implementation → review → completion. From the README: "As soon as it sees that you're building something, it doesn't just jump into trying to write code."

Four core principles:

Test-Driven Development — tests precede all code
Systematic over ad-hoc — process replaces guessing
Complexity reduction — simplicity is the primary goal
Evidence over claims — verify before declaring success

🔀 The philosophical split

Spec Kit is artifact-centric. The spec persists, evolves, and is the contract.
Superpowers is process-centric. The procedure persists; the artifact is whatever the procedure produces.

2. 🔄 Workflow & Mental Model

📘 Spec Kit's 7-step workflow

/speckit.constitution — Establish project governing principles
/speckit.specify — Define requirements and user stories
/speckit.clarify — Clarify underspecified requirements
/speckit.plan — Create technical implementation plans
Validate the plan for completeness
/speckit.tasks — Generate actionable task breakdowns
/speckit.implement — Execute tasks to build features

Three modes: 0-to-1 (greenfield), Creative Exploration (parallel implementations across stacks), Iterative Enhancement (brownfield).

🦸 Superpowers' 7 workflow stages

Brainstorming — Socratic questioning to refine ideas
Using Git Worktrees — Isolated branches with verified test baselines
Writing Plans — Break work into 2–5 minute tasks with exact specs
Subagent-Driven Development — Fresh subagent per task, two-stage review
Test-Driven Development — Strict RED-GREEN-REFACTOR
Requesting Code Review — Pre-review checklists, severity-based tracking
Finishing Development Branches — Merge/PR decision + cleanup

🎯 Key contrast

Spec Kit's workflow is linear and document-producing: each command emits an artifact (constitution, spec, plan, tasks).
Superpowers' workflow is stateful and execution-producing: each stage manipulates code, tests, branches, and subagent state.

3. 🏗️ Architecture & Primary Unit

📘 Spec Kit — Slash commands + templates

Six explicit, user-invoked slash commands (/speckit.constitution, /speckit.specify, /speckit.clarify, /speckit.plan, /speckit.tasks, /speckit.implement). Each is a template that produces a structured artifact stored under .specify/.

.specify/
├── memory/         # Constitution and governance
├── specs/          # Feature specifications by ID
├── scripts/        # Helper automation scripts
├── extensions/     # Custom extensions
├── presets/        # Workflow customizations
└── templates/      # Command templates

🦸 Superpowers — Skills + agents + plugins

14+ composable skills organized by category:

Testing: test-driven-development
Debugging: systematic-debugging, verification-before-completion
Collaboration: brainstorming, writing-plans, executing-plans, dispatching-parallel-agents, requesting-code-review, receiving-code-review, using-git-worktrees, finishing-a-development-branch, subagent-driven-development
Meta: writing-skills, using-superpowers

agents/        # Agent definitions
skills/        # Skill implementations (auto-triggered)
commands/      # CLI command definitions
.claude-plugin/, .codex-plugin/, .cursor-plugin/   # Per-host configs

🎬 Trigger model — the deepest difference

Spec Kit: human types /speckit.plan. Explicit, deterministic.
Superpowers: skill auto-fires when its description matches the situation. The agent doesn't decide to brainstorm; the brainstorming skill triggers because the user mentioned a vague idea.

This makes Spec Kit feel like a CLI you drive, and Superpowers feel like an operating system the agent inhabits.

4. 🤖 Agent / Tool Compatibility

Agent / Tool	Spec Kit	Superpowers
Claude Code	✅	✅ (official + Superpowers marketplace)
GitHub Copilot CLI	✅	✅
Gemini CLI	✅	✅
Cursor (CLI / IDE)	✅	✅ (plugin marketplace)
OpenAI Codex CLI / Codex App	✅	✅
OpenCode	—	✅
Qwen / Mistral / others	✅ (30+ agents total)	—

Spec Kit casts a wider net (30+ agents), selected at install time via --integration. Superpowers goes deeper per host, with first-class plugin packages tailored to each ecosystem.

5. 📦 Installation & Distribution

📘 Spec Kit

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Python 3.11+, Git, uv or pipx
Cross-platform (Linux/macOS/Windows)
Distributed only from GitHub — PyPI packages with the same name are not official

🦸 Superpowers

Claude plugin marketplace: /plugin install superpowers@claude-plugins-official
Superpowers marketplace registration
Per-agent installation flows for Codex, Cursor, OpenCode, Copilot CLI, Gemini CLI

Spec Kit is a single CLI you install once and configure per project. Superpowers is a plugin you install per agent host, with the host's plugin system managing updates.

6. 🧩 Customization & Extensibility

📘 Spec Kit

Extensions — add new capabilities (Jira sync, post-implementation review, …)
Presets — customize existing workflows (compliance formats, terminology localization)
100+ community-contributed extensions across docs, code, process, integration, visibility categories

🦸 Superpowers

Skills are the extension primitive — write your own SKILL.md with a description that triggers in your situation
The writing-skills meta-skill teaches the agent how to author new skills
using-superpowers documents how skills compose

🔍 Comparison

Spec Kit's extension model is catalog-driven — you browse and adopt prebuilt pieces.
Superpowers' extension model is author-driven — the framework actively supports you writing the next skill.

7. 🌟 What Each Does Especially Well

📘 Spec Kit shines when…

You need traceability from requirement to code (audits, compliance, regulated industries)
A product manager / non-engineer owns the spec and engineers consume it
You want to swap stacks: regenerate the same spec into Go, Python, TypeScript
Your org already thinks in terms of PRDs, RFCs, and design docs
You need enterprise-style governance with constitution-level constraints

🦸 Superpowers shines when…

You want the agent to run autonomously for hours without going off-rails
You want strict TDD baked into the agent's behavior, not just hoped for
You're orchestrating parallel subagents and need built-in review patterns
You need evidence-based completion — agent must prove it worked, not claim it
You're operating at the frontier of agent autonomy and want guardrails by default

8. ⚖️ Tradeoffs & Limitations

📘 Spec Kit

Heavier upfront cost — writing a constitution and spec before any code feels slow for small tasks
Less suited for exploratory hacking — the workflow assumes you know roughly what you want
Spec drift risk — if the team edits code without updating specs, the "single source of truth" erodes
Document-heavy — generates many markdown artifacts that need maintenance

🦸 Superpowers

Opinionated — the workflow assumes you want TDD, worktrees, subagent orchestration; if you don't, friction is high
Complexity floor — even small tasks pay some procedural overhead
Learning curve — 14+ skills and a meta-vocabulary (subagent-driven-development, verification-before-completion) take time to internalize
Auto-triggering can surprise — a skill firing unexpectedly can derail a session if descriptions are loose

9. 🤝 How They Could Coexist

These are not mutually exclusive. A team could realistically:

Use Spec Kit for the what — constitution, spec, plan, tasks committed to the repo as durable artifacts
Use Superpowers for the how — once tasks exist, Superpowers' TDD, worktree, subagent, and review skills execute them

The artifacts Spec Kit produces (.specify/specs/<id>/tasks.md) are exactly the kind of plan Superpowers' executing-plans skill is designed to consume. The two systems target different layers of the same problem.

9a. 🛠️ The Best Way to Combine Both — A Practical Guide

The mental model in one sentence:

Spec Kit plans WHAT to build. Superpowers controls HOW it gets built.

Spec Kit gives you durable, human-readable artifacts (constitution → spec → plan → tasks). Superpowers takes those tasks and executes them with TDD, worktrees, subagents, and review baked in. You hand off at the task list.

⚙️ One-time setup (do this once per machine + once per repo)

On your machine:

Install Spec Kit:

   uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Install Superpowers in your agent host. For Claude Code:

   /plugin install superpowers@claude-plugins-official

In your repo (once):

Initialize Spec Kit with your agent: specify init --integration claude-code (or whichever agent you use).
Run /speckit.constitution once to set project-wide rules. Add a single line that bridges the two systems: > "Implementation of any task list MUST follow the Superpowers workflow: worktree → TDD (red-green-refactor) → subagent-driven execution → code review → finish-branch."
Commit .specify/ to the repo. Add .claude/ (or your host's plugin dir) per your team's policy.

That's the entire setup. From here on, every feature follows the same loop.

🔁 The per-feature loop (the one you actually use)

Run these in order. Each step is a single command or short prompt.

Step	Tool	Command / Prompt	What you get
1	Superpowers	"Let's brainstorm: I want to add X." (triggers `brainstorming` skill)	Clarified idea, alternatives considered
2	Spec Kit	`/speckit.specify`	`specs/<id>/spec.md` — the requirements
3	Spec Kit	`/speckit.clarify`	Open questions resolved
4	Spec Kit	`/speckit.plan`	`specs/<id>/plan.md` — technical approach
5	Spec Kit	`/speckit.tasks`	`specs/<id>/tasks.md` — ordered, small tasks
6	Superpowers	"Use git worktree for this feature." (triggers `using-git-worktrees`)	Isolated branch with green test baseline
7	Superpowers	"Execute `specs/<id>/tasks.md` using subagent-driven development with TDD."	Code, written test-first, one subagent per task
8	Superpowers	"Request code review." (triggers `requesting-code-review`)	Severity-tagged punch list
9	Superpowers	"Finish the development branch." (triggers `finishing-a-development-branch`)	PR opened or merged + cleanup

That's it. Spec Kit owns steps 2–5. Superpowers owns steps 1, 6–9. The handoff happens at tasks.md.

📜 The two non-obvious rules that make this combo work

Rule 1 — Don't skip /speckit.tasks, even when you're tempted.
Superpowers' executing-plans skill is designed to consume small (2–5 minute) tasks. Spec Kit's /speckit.tasks produces exactly that shape. Skipping it forces Superpowers to break the work down at execution time, which is slower and lower quality.

Rule 2 — Don't let Superpowers re-plan what Spec Kit already planned.
When you start step 7, explicitly say: "The plan is already in specs/<id>/tasks.md. Don't re-plan — execute." Otherwise Superpowers' writing-plans skill may auto-fire and duplicate work.

📋 One-line prompt template for the execution handoff

Paste this when you're ready to switch from Spec Kit (planning) to Superpowers (execution):

Execute specs/<feature-id>/tasks.md using the Superpowers workflow:
create a worktree, follow strict TDD per task, dispatch one subagent per
task, run code review at the end, then finish the branch. Do not re-plan —
the task list is the contract.

📏 When to scale down (don't over-engineer small work)

For a one-line bug fix or a typo, both frameworks are overkill. A reasonable size cutoff:

Task size	Use
< 30 minutes, < 3 files	Just prompt directly. Skip both.
30 min – 2 hours, single concern	Superpowers only — brainstorm + TDD + finish-branch
> 2 hours, multi-component, or shipped to users	Both — full Spec Kit planning, then Superpowers execution
Anything regulated / audited	Both, mandatory — the spec trail is part of compliance

🚫 Anti-patterns to avoid

❌ Running /speckit.implement AND Superpowers. Pick one for execution. /speckit.implement is Spec Kit's own executor; Superpowers replaces it for this combo.
❌ Editing code without updating the spec. If reality diverges from spec.md, your audit trail dies. Re-run /speckit.specify for the changed area.
❌ Letting subagents read the whole .specify/ tree. Pass them only the specific task they're executing — context discipline still matters.
❌ Skipping the constitution. Without it, Superpowers and Spec Kit each impose their own defaults and you'll feel the friction.

✅ A 60-second mental checklist before starting any feature

Is there a spec? If no → /speckit.specify.
Are tasks small and ordered? If no → /speckit.tasks.
Am I on a worktree with green tests? If no → trigger using-git-worktrees.
Did I tell the agent "don't re-plan, execute"? If no → say it now.
Will I review the PR diff myself before merging? If no → stop.

If all five are yes, you're using the combo correctly.

10. 🧭 Quick Decision Guide

📘 Pick Spec Kit if you…

Want specs as durable, reviewable artifacts
Need cross-stack portability (regenerate same spec → different language)
Work in an environment where PRDs/RFCs are already a norm
Value broad agent compatibility (30+ tools)
Want a GitHub-backed, enterprise-friendly project

🦸 Pick Superpowers if you…

Want the agent itself to behave more like a senior engineer
Need strict TDD, worktree isolation, subagent orchestration out of the box
Run long, autonomous sessions and need guardrails
Prefer auto-triggered skills over user-invoked commands
Want a writable, composable skill system you can extend yourself

🤝 Pick both if you…

Want artifact-driven planning + workflow-driven execution
Are willing to invest in setup for a more rigorous overall pipeline

11. 📊 At-a-Glance Summary

Dimension	Spec Kit	Superpowers
Owner	GitHub	Jesse Vincent / Prime Radiant
Methodology	Spec-Driven Development	Agentic SDLC w/ enforced workflow
Primary unit	Slash command + spec template	Auto-triggered skill
Trigger model	User-invoked	Context-matched
Output	Spec → plan → tasks → code	Branch + tests + code + review
TDD enforcement	Optional	Mandatory (built-in skill)
Subagent orchestration	Not core	First-class
Worktree management	Not core	First-class
Constitution / governance	Built-in (`/speckit.constitution`)	Not core
Stack swapping	Strong (regen from spec)	Weak (workflow is stack-agnostic but no regen)
Agent reach	30+ agents	~6 first-class hosts
Install	`uv tool install`	Plugin marketplace per host
Extensibility	Extensions + presets (catalog)	Skills (author-it-yourself)
Best fit	Greenfield, brownfield, regulated work	Long autonomous sessions, parallel agents
License	MIT	MIT

Generated 2026-04-25. Both projects are evolving rapidly — verify version-specific details against their READMEs before adopting.

If you found this helpful, let me know by leaving a 👍 or a comment!, or if you think this post could help someone, feel free to share it! Thank you very much! 😃

🚀 Claude Code: From Zero to Hero 🤖

Truong Phung — Sat, 25 Apr 2026 09:26:55 +0000

A practical, progressive guide to getting serious value out of Claude Code. Each section is short, actionable, and builds on the one before. If you already know the basics, skim the early parts and jump to where it gets interesting — the later sections are where most users leave value on the table.

📖 How to read this guide
Every section ends with a Try this now box. Do the exercise before moving on. Reading alone will not make you faster; typing will.

🌱 Part 1 — Zero

What Claude Code actually is
Install and first run
Your first real task
The interface: commands and shortcuts you need on day one

🔧 Part 2 — Apprentice

CLAUDE.md — teaching Claude about your project
Permissions — stop approving the same commands over and over
Plan mode and review discipline
Context hygiene — the skill nobody teaches

⚡ Part 3 — Journeyman

Slash commands — your personal shortcuts
Subagents — delegation and isolation
Skills — reusable procedures
Hooks — deterministic automation

🏆 Part 4 — Hero

MCP servers — connecting external systems
Prompting for real work
Team setup — making Claude Code a shared asset
Debugging Claude when it goes sideways
The habits that separate heroes from tourists

🌱 Part 1 — Zero

1. 🤖 What Claude Code actually is

Claude Code is an AI coding agent that runs in your terminal (and inside VS Code, JetBrains, etc.). It reads your codebase, writes and edits files, runs shell commands, and iterates on tasks — all with your permission.

Three mental models that will save you hours of confusion:

It's a collaborator, not a compiler. You describe intent; it proposes actions and waits for approval on anything risky. Give it context the way you'd brief a new teammate.
It is stateless between sessions, but not between turns. Close the terminal and it forgets the conversation. That's why project memory (CLAUDE.md) exists — to carry the important stuff forward.
Every tool call is explicit. Reading a file, editing it, running a shell command — these are all visible tool calls. If it's making changes you don't want, you can see exactly where.

What it is not: a chat wrapper. Claude Code has a rich configuration surface — permissions, slash commands, subagents, skills, hooks, MCP servers — and the difference between a tourist and a power user is almost entirely in how those are set up.

2. 📦 Install and first run

Install the CLI (one command, no account setup beyond API access):

npm install -g @anthropic-ai/claude-code

Verify:

claude --version

Start it inside a project directory:

cd ~/projects/my-repo
claude

On first run it will walk you through authentication. After that, you're looking at an interactive prompt waiting for input.

🔥 Try this now
Install Claude Code, cd into any project you have, and run claude. Type /help and read the entire help output. Don't skip this — 30% of the things people ask me could be answered by reading /help once.

3. 🎯 Your first real task

Don't start with "hello world." Start with something you'd actually ask a teammate.

A good first prompt:

Read the README.md and the top-level directory, then give me a two-paragraph summary of what this project does and how the pieces fit together.

Why this works: it's bounded, read-only, and forces Claude to explore the codebase — which is how you'll learn what tools it has.

Watch what happens:

It calls Read on README.md
It runs ls via Bash
Maybe it peeks at a few key files
It answers in prose

You'll see tool calls scroll by. Each one is a concrete action. This transparency is the whole point — you're not trusting a black box.

Now try something active:

Add a CHANGELOG.md at the repo root with a "Keep a Changelog" template and an Unreleased section.

It will ask permission to write the file. Say yes. Look at the diff it produced. Ask it to change something trivial ("add a link to keepachangelog.com at the top"). Notice how it edits in place rather than re-writing the file.

🔥 Try this now
Pick one real, small task in a real repo — not a toy — and ask Claude Code to do it end to end. Something like "write me a script that renames all .jpg to .png" or "refactor this function to use async/await." Review every tool call. Reject one thing you don't like and watch it adjust.

4. ⌨️ The interface

Key commands (type these at the prompt)

Command	What it does
`/help`	Full command reference
`/clear`	Wipe the conversation — start fresh without quitting
`/model`	Switch between models (Opus / Sonnet / Haiku)
`/init`	Bootstrap a `CLAUDE.md` for the current project
`/status`	Show what mode you're in, token usage, etc.
`/review`	Review the current branch's changes
`/compact`	Manually compact conversation context to free room
`Esc`	Interrupt Claude mid-action
`Shift+Tab`	Cycle through permission modes (normal → auto-accept → plan)

Permission modes (the single most useful thing to understand)

Claude Code has three main modes you'll toggle between:

Normal — Claude asks before every tool call that isn't pre-approved. Safe default.
Auto-accept (a.k.a. "YOLO mode" or "accept edits") — Claude runs without asking. Use when you trust the task and want speed. Never use for destructive or networked operations on a repo you care about.
Plan mode — Claude explores and reasons but cannot modify anything until you approve a plan. Use for anything non-trivial. This is the single biggest time-saver most people ignore.

Cycle them with Shift+Tab. The current mode is shown in the status area.

Interrupting

If Claude is going down the wrong path, hit Esc. Don't wait for it to finish and then complain — redirect mid-flight. It handles interruption well.

🔥 Try this now
Start a session, press Shift+Tab three times and observe how the mode indicator changes. Then try the same trivial task ("add a blank line to the README") in each mode and feel the difference. Also press Esc while it's mid-action at least once. Getting comfortable with these three keys is worth more than any config.

🔧 Part 2 — Apprentice

5. 📄 CLAUDE.md

CLAUDE.md is the single most valuable file in a Claude-Code-enabled repo. It's plain markdown placed at the repo root (and optionally in subdirectories) that Claude reads at the start of every session.

Think of it as the onboarding doc for a new engineer, except the engineer reads it every single day and has perfect recall.

What to put in it

Architecture — the service boundaries, the data flow, who calls whom
How to run things — exact commands, copy-paste runnable
Conventions that the code alone can't tell you — "we prefer functional components," "all errors must be wrapped with fmt.Errorf," etc.
Pitfalls — things that have burned the team before ("never edit an applied migration")
End-to-end checklists for common tasks ("adding a feature touches these 9 layers, in this order")

What to leave out

Anything ls or git log can answer
Narrative prose, history, aspirations
Secrets
Step-by-step tutorials (link to them instead)

Layering

You can have nested CLAUDE.md files. When Claude works inside a subdirectory, the nested file is loaded too. Use this for service-specific conventions in a monorepo.

repo/
  CLAUDE.md                  # root — cross-cutting context
  backend-go/CLAUDE.md       # Go-specific conventions
  backend-python/CLAUDE.md   # Python-specific conventions
  frontend/CLAUDE.md         # React/TS-specific conventions

There's also ~/.claude/CLAUDE.md — personal preferences applied in every project on your machine (e.g., "I prefer tabs over spaces in my personal scripts").

Rules of thumb

Every line competes for context budget. Treat it like a tweet — if removing a line wouldn't hurt, remove it.
Prefer commands over instructions. make test-integration beats a paragraph about integration tests.
State constraints explicitly. "Integration tests require Docker." not "We have integration tests."
Link, don't duplicate. If your style guide lives elsewhere, link it.

🔥 Try this now
In your project, run /init. Claude will scan the codebase and draft a CLAUDE.md for you. Then read it critically and delete half the content. The short version is usually better. Commit it.

6. 🔐 Permissions

By default, Claude asks before running any shell command or editing any file. That's safe but interrupt-heavy.

Create .claude/settings.json in your repo:

{
  "permissions": {
    "allow": [
      "Bash(go test:*)",
      "Bash(pnpm test:*)",
      "Bash(npm run build:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)"
    ],
    "deny": [
      "Bash(sudo:*)",
      "Bash(rm -rf /:*)",
      "Bash(git push --force:*)"
    ]
  }
}

Pattern rules

Bash(cmd:*) — allow cmd followed by any arguments
Bash(cmd arg1:*) — allow cmd arg1 with anything after
Bash(cmd) — exact match only
deny always wins over allow

Personal vs team

.claude/settings.json — committed, shared with the team
.claude/settings.local.json — git-ignored, personal tweaks (your favorite CLIs, local env)
~/.claude/settings.json — global, applies to every project on your machine

The golden rule

Never blanket-allow Bash(*). The permission prompt is cheap; a destructive command you didn't mean to run is expensive. Keep the deny list tight and aggressive.

🔥 Try this now
Look back at your last Claude Code session. Which commands did you approve three or more times? Those are your candidates for the allow list. Add them to .claude/settings.json and commit. Do NOT add things you only approved once — premature allow-listing is how people accidentally yield too much.

7. 🗺️ Plan mode

For any task that is more than "rename this variable," press Shift+Tab until you're in Plan mode before you start. Then prompt:

Plan out what it would take to add rate limiting to the /api/login endpoint. Don't make any changes — just propose the plan.

Claude will explore, read code, think, and produce a concrete plan (files to touch, order of operations, tradeoffs). You review the plan, ask follow-up questions, adjust the approach. When you're happy, you exit plan mode and tell it to execute.

This pattern catches an enormous class of "Claude went off and did the wrong thing" problems. Five minutes of planning saves an hour of re-doing.

When to skip plan mode

Trivial edits (typo fix, one-line change)
Tasks where "wrong direction" has no cost (exploratory prototyping)
When you're already in a detailed prompt-response loop and have alignment

When to always use plan mode

Any change touching more than 3 files
Any migration or refactor
Any task involving external systems (APIs, databases, deploys)
Anything where you'd review a PR carefully — if it needs review, it needs a plan first

🔥 Try this now
Take a real task on your backlog that you've been putting off. Enter plan mode. Ask for a plan. Read it critically. You'll find that either (a) the plan reveals the task is bigger than you thought — which is useful information — or (b) you're now ready to execute with confidence.

8. 🧹 Context hygiene

The single most underrated skill. Long conversations accumulate irrelevant context, which degrades Claude's attention and eats your token budget.

Rules

Start a new session for an unrelated task. Don't use the same conversation to fix a bug, add a feature, and then write release notes.
Use /clear aggressively. When you shift focus, clear the conversation. The cost of re-explaining is usually less than the cost of carrying accumulated noise.
Don't paste huge logs. If the full stack trace is 2000 lines, paste the top 20 and let Claude ask for more if needed.
Delegate searches. "Find every place X is used" is a job for a subagent (covered in Part 3), not your main conversation. A subagent can ingest a mountain of search output and return a short summary, keeping your main context clean.
Use /compact when context fills up. It summarizes history and continues with less bloat. Better than letting auto-compaction kick in mid-task.

Signs your context is polluted

Claude makes the same small mistake it already corrected earlier
It references files that have nothing to do with the current task
It proposes solutions that contradict constraints you already set
Responses feel generic and hedge-y

When you see these, /clear is almost always the right move.

🔥 Try this now
Next time you finish a task, before starting a new one, run /clear. Build the muscle. Most people keep the conversation running forever and wonder why Claude gets worse over time.

⚡ Part 3 — Journeyman

9. ⚡ Slash commands

A slash command is a markdown file in .claude/commands/ that becomes an invocable shortcut. The file body becomes the prompt; $ARGUMENTS is substituted with whatever you type after the command name.

Minimal example

.claude/commands/review.md:

Review the uncommitted changes on this branch.

Focus on:
- Security issues (injection, XSS, unsafe deserialization)
- API contract changes that would break callers
- Missing tests for new code paths
- Unused imports, dead code

Don't modify files — review only. Output a punch list.

Invoke with /review.

With arguments

.claude/commands/test.md:

Run the test suite for the specified service. Argument: $ARGUMENTS

Rules:
- If argument is "go": `cd backend-go && go test ./... -race -count=1`
- If argument is "python": `cd backend-python && uv run pytest -v`
- If argument is "frontend": `cd frontend && pnpm test`
- If argument is "all" or empty: run all three, stop on first failure

Invoke with /test go or /test all.

Frontmatter (optional)

---
description: Open a PR for the current branch with auto-generated title and body
argument-hint: "[issue-number]"
allowed-tools: ["Bash", "Read", "Write"]
model: opus
---

Steps:
1. Ensure branch is pushed
2. Read commits since diverging from main
3. Draft a PR title and body based on the commits
4. Run `gh pr create` with the drafted content
5. If $ARGUMENTS is present, add "Closes #$ARGUMENTS" to the body

Gotchas

Flat namespace. .claude/commands/git/commit.md becomes /commit, not /git:commit. Name files carefully.
No code execution in the markdown file itself — the body is sent as a prompt. Claude then decides what to run.
Keep them focused. If a command tries to do too much, split it.

Slash command vs skill vs subagent

	Use when
Slash command	User explicitly triggers a workflow (`/test`, `/lint`, `/pr`)
Skill	Reusable procedure Claude should apply when relevant (user doesn't type it)
Subagent	You want an isolated context / fresh conversation for a big sub-task

🔥 Try this now
Identify the three prompts you most commonly type. Turn each into a slash command. You'll feel the productivity gain immediately.

10. 🤝 Subagents

Subagents are specialized Claude instances that run in a separate conversation with their own system prompt and tool permissions. The main agent delegates work to them.

Why this matters:

Context isolation. The subagent doesn't see your main conversation. Great for independent reviews — it can't be biased by your prior reasoning.
Parallelism. The main agent can run multiple subagents concurrently. Perfect for "check A, B, and C independently."
Tool scoping. A "reviewer" subagent can be given read-only tools, so it literally can't write files even if asked.

Defining a subagent

Create .claude/agents/migration-reviewer.md:

---
description: Review SQL migrations for safety. Use proactively whenever a migration file is added or modified.
tools: ["Read", "Bash", "Grep"]
model: opus
---

You are a database migration safety reviewer. For any migration under `backend-go/migrations/`, check:

1. Does it have both Up and Down blocks?
2. Are NOT NULL columns added with a default, or is there a backfill step?
3. Are indexes created CONCURRENTLY on large tables?
4. Is there anything irreversible (DROP COLUMN, DROP TABLE) that needs a rollback plan?

Report findings as a punch list. Do not modify files.

The main agent will now auto-invoke this whenever a migration changes (because of the "Use proactively" phrasing).

Built-in agent types

Claude Code ships with a few built-in agent types you can use without defining your own:

Explore — fast codebase search, great for "find every place X is used"
general-purpose — the default, for any research task

When to use a subagent

Research/exploration that will generate lots of output you don't want in your main context
Independent review where you want an unbiased second opinion
Parallelizable work — three questions that don't depend on each other

When NOT to use a subagent

Small targeted tasks — spawning a subagent has overhead; for a 30-second task, just do it yourself
Tasks where you want to stay in conversation — the subagent returns one message and is gone; you can't iterate with it

🔥 Try this now
Next time you need to understand an unfamiliar area of your codebase, prompt the main agent: "Spawn an Explore subagent to find every place authenticate() is called, what it returns, and who handles its errors. Give me a short report." Notice how your main context stays clean.

11. 💡 Skills

Skills are reusable procedures that Claude loads when relevant. Unlike slash commands (user-triggered) or subagents (fresh-context delegation), skills layer procedural knowledge onto your current conversation.

Directory layout

.claude/skills/
  release-notes/
    SKILL.md          ← required
    template.md       ← optional supporting files
    scripts/
      extract.sh      ← optional helper scripts

SKILL.md format

---
description: Generate release notes from git log since the last tag. Invoke when the user asks for a changelog, release notes, or summary of recent changes.
---

# Release Notes Skill

When invoked:

1. Find the last tag: `git describe --tags --abbrev=0`
2. Run `git log <tag>..HEAD --pretty=format:'%h %s (%an)' --no-merges`
3. Group commits by conventional prefix (feat/fix/chore/docs/refactor)
4. Format using `template.md` in this skill directory
5. Output the final markdown — do not write to a file unless asked

Auto-discovery

Claude reads the description of every available skill at session start. When your prompt matches a skill's description, it's invoked automatically.

This is why the description matters more than anything else in the skill. Write it like a trigger: when should this fire?

Bad: "Release notes generator."
Good: "Generate release notes from commits since the last git tag. Invoke when the user asks for a changelog, release notes, or summary of changes since vX.Y.Z."

Skill vs slash command — the quick heuristic

Ask: "Will the user explicitly type /skill-name?"

Yes → make it a slash command
No, but Claude should apply it when a situation arises → make it a skill

Built-in skills

Claude Code ships with several built-in skills (update-config, simplify, pr, lint, test, gen, build, migrate, review, security-review, etc.). Run /help to see what's currently registered.

🔥 Try this now
Pick a procedure your team does routinely — releasing a version, writing a migration, auditing a feature — and turn it into a skill. Craft the description carefully so Claude auto-invokes it.

12. 🪝 Hooks

Hooks are shell commands the harness (not Claude) runs in response to events. They run outside Claude's decision loop, which makes them the right tool for:

Enforcing something deterministically (auto-format after edit)
Injecting context (show branch name on session start)
Blocking unsafe actions (refuse writes to /etc/)

A memory instruction like "always format Go files" is advisory — Claude might forget. A hook is a hard guarantee.

Shape

Hooks live in .claude/settings.json:

{
  "hooks": {
    "<EventName>": [
      {
        "matcher": "<pattern>",
        "hooks": [
          { "type": "command", "command": "<shell>" }
        ]
      }
    ]
  }
}

Events you'll actually use

Event	Fires when
`PreToolUse`	Before a tool runs. Exit 2 blocks it.
`PostToolUse`	After a tool succeeds. Good for auto-format.
`UserPromptSubmit`	After user sends a prompt. Can inject context.
`SessionStart`	Session boot.
`Stop`	End of Claude's turn.

Exit codes and I/O

0 — success; stdout becomes context for Claude
2 — blocking; stderr is shown to Claude as the reason to retry/adjust
other — non-blocking error; logged and ignored

Hooks receive the event payload as JSON on stdin. Parse with jq:

file=$(jq -r '.tool_input.file_path // empty')

Example 1 — auto-format after edit

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "file=$(jq -r '.tool_input.file_path // empty'); [[ \"$file\" == *.go ]] && gofmt -w \"$file\"; [[ \"$file\" == *.py ]] && ruff format \"$file\"; true"
          }
        ]
      }
    ]
  }
}

Example 2 — block writes to generated files

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "file=$(jq -r '.tool_input.file_path // empty'); if [[ \"$file\" == *generated/* ]]; then echo 'Do not edit generated files — re-run code generation instead.' >&2; exit 2; fi"
          }
        ]
      }
    ]
  }
}

Example 3 — inject branch info at session start

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "echo \"Branch: $(git branch --show-current)\"" }
        ]
      }
    ]
  }
}

When hooks are the wrong tool

"Remind Claude to write tests" → put it in CLAUDE.md, not a hook
"Run tests only when I say" → slash command, not a hook
"Apply procedure X in situation Y" → skill, not a hook

Hooks are for the things the harness must enforce regardless of what Claude decides.

🔥 Try this now
Add a PostToolUse hook that auto-formats any file Claude edits in your project's language. One concrete step that will improve every future session.

🏆 Part 4 — Hero

13. 🔌 MCP servers

Model Context Protocol (MCP) servers extend Claude with external tools — Slack, Linear, Sentry, Postgres, your internal APIs. Configure them in .claude/settings.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgres://dev:dev@localhost:5432/app"]
    }
  }
}

Popular servers: postgres, github, slack, linear, sentry, puppeteer, fetch. See the MCP server directory.

Before adding an MCP server, ask:

"Would a shell command work?"

A psql invocation in your permission allowlist is simpler than a Postgres MCP server 90% of the time. MCP is right when:

The tool requires stateful auth (OAuth flows, API keys that rotate)
The output is richly structured (JSON APIs where Claude needs field-level access)
You want Claude to call the tool across many turns without re-establishing connection

If you're adding an MCP server "because I saw one for X," check whether curl, gh, psql, or aws already solves the problem.

14. ✍️ Prompting for real work

Prompting advice is often generic. Here's what actually matters for Claude Code specifically:

1. Scope bounded, context explicit

Bad: "Fix the tests."
Good: "Fix the flaky test in backend-go/internal/service/user_test.go. It fails about one run in ten. The last failure log is in /tmp/test-output.log."

The more of the context you provide up front, the less Claude has to spend tokens discovering.

2. State constraints before action

"Don't change the public API."
"Only modify files under frontend/src/components/."
"If the fix requires more than 50 lines of changes, stop and tell me — don't barrel through."

These constraints prevent whole classes of "this isn't what I wanted" outcomes.

3. Ask for a plan first on anything non-trivial

Covered in section 7. Plan mode is free; re-doing work is expensive.

4. Be honest about your knowledge

"I don't know this codebase well; help me understand X before we change it" produces better results than pretending to know.

5. Push back on mediocre output

If Claude produces something that works but isn't good, say so: "That works, but it has three issues: (a) ..., (b) ..., (c) .... Please revise." Don't accept first-draft output on things that matter.

6. Use "one-shot" framing for tightly-scoped tasks

"Write a bash script that does X. One shot — no back-and-forth. Output the whole script." forces a more thorough first response than open-ended prompting.

7. For debugging, state the hypothesis

Bad: "Why is this broken?"
Good: "I think this is broken because the deploy step doesn't wait for the DB migration to finish, but I'm not sure. Verify or refute that hypothesis first."

Hypothesis-first debugging is 3× faster than open-ended investigation.

15. 👥 Team setup

Taking Claude Code from "a tool each person uses" to "a shared team asset" is high-leverage. Here's the checklist:

Committed to the repo

CLAUDE.md at root, per-service where useful
.claude/settings.json — shared permissions and hooks
.claude/commands/ — team slash commands (/test, /lint, /pr, /review, /deploy-staging)
.claude/agents/ — team subagents (reviewers, explorers)
.claude/skills/ — team procedures (release notes, migration review, on-call runbook)

Gitignored

.claude/settings.local.json — personal overrides
.env — secrets

Onboarding new engineers

Every new hire spends the first 30 minutes of day one:

Reading CLAUDE.md and every nested CLAUDE.md
Skimming .claude/commands/ — what shortcuts exist
Copying .env.example → .env
Running make dev (or equivalent) to verify the stack boots
Adding personal approvals to .claude/settings.local.json (not the shared file)

Keeping it fresh

Review CLAUDE.md quarterly. Stale guidance is worse than no guidance.
Add a pitfall every time someone gets burned. Post-incident: "update CLAUDE.md?" should be on the checklist.
Prune. If a slash command isn't used in a month, delete it. If CLAUDE.md has grown past ~300 lines, split it.

16. 🐛 Debugging Claude

When things go wrong, the problem is almost always one of these:

Symptom	Likely cause	Fix
Claude keeps asking to run a command I want pre-approved	Not in `permissions.allow`, or pattern too narrow	Add `Bash(cmd:*)` to `.claude/settings.json`
My hook isn't firing	Wrong event name, wrong matcher, or bad JSON	Validate JSON; re-check event name; test the command in isolation
Claude edits files but skips formatting	`PostToolUse` hook crashed silently	End hook command with `
Slash command not found	File naming collision (flat namespace)	Rename file; put it directly in {% raw %}`.claude/commands/`
`~/.claude/CLAUDE.md` isn't being read	It is — but per-project `CLAUDE.md` takes precedence for overlapping topics	Split clearly: global in `~/.claude`, project in repo
Subagent gives a different answer than main agent	Expected — it has isolated context by design	If you want shared context, don't use a subagent
Claude forgets between sessions	Facts were only in chat, not in `CLAUDE.md`	Move enduring facts to `CLAUDE.md`
Hook blocks every command unexpectedly	Exit code 2 is a hard block	Reserve exit 2 for real blocks; use 0 for non-blocking
Claude keeps making the same mistake	Context is polluted with contradictory info	`/clear` and re-prompt with explicit constraints
Response is generic and useless	Claude lacks context to answer well	Give it a file to read, a command to run, or narrow the scope

Using `--debug`

Run Claude Code with --debug to see detailed logs — hook invocations, tool calls, timing. Essential when something silent is misbehaving.

The "read it back" trick

When Claude produces output you disagree with, prompt: "Read back to me your understanding of what I asked for." Usually reveals the specific misinterpretation in seconds. Cheaper than re-arguing.

17. 💪 Habits

A list of habits that separate the heroes from the tourists. None of them are secret. All of them are practiced, not learned.

✅ Do

Plan before you build. For any non-trivial task, use plan mode or ask for a plan.
Review every diff before accepting. Claude is fast; a fast wrong change is still wrong.
Clear context aggressively. Start new sessions for unrelated work.
Update CLAUDE.md when you get burned. The next person (or your future self) shouldn't repeat the mistake.
Use subagents for exploration. Keep your main context clean.
Push back on mediocre output. Say "that's not quite right because X; revise."
Commit your .claude/ configuration. It's team infrastructure, not personal config.
Keep denies aggressive, allows minimal. sudo, rm -rf /, git push --force should always be blocked.

❌ Don't

Don't blanket-allow Bash(*). The cost of permission prompts is much less than the cost of one accidental destructive command.
Don't paste 2000-line logs. Paste the relevant 20 lines.
Don't accept first-draft output on things that matter. Iterate.
Don't keep one session running forever. Context rot is real.
Don't put secrets in CLAUDE.md or the chat. Ever.
Don't skip hooks (--no-verify) without a specific reason. Fix the real issue.
Don't build elaborate configuration before you've used the defaults for a week. Start simple. Add surfaces when you feel the pain.

📈 The progression

You're a tourist if you:

Type freeform prompts, approve everything one by one, never configure anything

You're an apprentice if you:

Have a CLAUDE.md, permission allow list, and use plan mode regularly

You're a journeyman if you:

Have slash commands for your common workflows, use subagents for exploration, and have at least one hook enforcing a guarantee

You're a hero if you:

Treat .claude/ as team infrastructure, prune it regularly, and notice when you're using the wrong surface (skill when it should be a command, hook when it should be memory)

📚 Further reading

Official docs — https://docs.claude.com/en/docs/claude-code
MCP server directory — https://github.com/modelcontextprotocol/servers

📋 One-page summary

If you remember nothing else:

Put enduring facts in CLAUDE.md. Keep it tight.
Pre-approve your common commands in .claude/settings.json. Never Bash(*).
Use plan mode (Shift+Tab) before any non-trivial task.
Clear context between unrelated tasks (/clear).
Turn your repeat prompts into slash commands.
Use subagents for big searches and independent reviews.
Use skills for procedures Claude should apply automatically.
Use hooks when you need a hard guarantee, not a polite suggestion.
Review every diff. Push back on mediocre output.
Update configuration when you get burned — once, not twice.

🚢 Happy shipping.

If you found this helpful, let me know by leaving a 👍 or a comment!, or if you think this post could help someone, feel free to share it! Thank you very much! 😃

🤖 Learn Harness Engineering by Building a Mini Openclaw 🦞

Truong Phung — Sat, 25 Apr 2026 08:34:29 +0000

🔀 Origin & Modifications
🤔 What is this?
🏗️ Architecture
🔗 Section Dependencies
⚡ Quick Start
🗺️ Learning Path
📋 Section Details
📁 Repository Structure
📦 Prerequisites
🧩 Dependencies
🔗 Related Projects

Git repo: truongpx396/learn-harness-engineering-by-building-mini-openclaw

🔀 Origin & Modifications

This repository is a fork of shareAI-lab/claw0

Changes made in this fork:

🔄 SDK migration: Migrated from the Anthropic SDK to the OpenAI SDK, making all sections compatible with any OpenAI-compatible endpoint.
🖥️ Local model support: Added setup guides for running fully offline with LM Studio, Ollama, and GPT4All — no cloud API required.
⚙️ .env-based configuration: Introduced OPENAI_BASE_URL and MODEL_ID environment variables so you can point any section at a different provider or local server without touching the code.

All credit for the original curriculum, architecture, and teaching approach goes to shareAI-lab.

🚀 From Zero to One: Build an AI Agent Gateway

10 progressive sections -- every section is a single, runnable Python file.
code + docs co-located.

🤔 What is this?

Most agent tutorials stop at "call an API once." This repository starts from that while loop and takes you all the way to a production-grade gateway.

Build a minimal AI agent gateway from scratch, section by section. 10 sections, 10 core concepts, ~7,000 lines of Python. Each section introduces exactly one new idea while keeping all prior code intact. After all 10, you can read OpenClaw's production codebase with confidence.

s01: Agent Loop           -- The foundation: while + finish_reason
s02: Tool Use             -- Let the model call tools: dispatch table
s03: Sessions & Context   -- Persist conversations, handle overflow
s04: Channels             -- Telegram + Feishu: real channel pipelines
s05: Gateway & Routing    -- 5-tier binding, session isolation
s06: Intelligence         -- Soul, memory, skills, prompt assembly
s07: Heartbeat & Cron     -- Proactive agent + scheduled tasks
s08: Delivery             -- Reliable message queue with backoff
s09: Resilience           -- 3-layer retry onion + auth profile rotation
s10: Concurrency          -- Named lanes serialize the chaos

🏗️ Architecture

+--- agent layers ---+
|                                                     |
|  s10: Concurrency  (named lanes, generation track)  |
|  s09: Resilience   (auth rotation, overflow compact)|
|  s08: Delivery     (write-ahead queue, backoff)     |
|  s07: Heartbeat    (lane lock, cron scheduler)      |
|  s06: Intelligence (8-layer prompt, hybrid memory)  |
|  s05: Gateway      (WebSocket, 5-tier routing)      |
|  s04: Channels     (Telegram pipeline, Feishu hook) |
|  s03: Sessions     (JSONL persistence, 3-stage retry)|
|  s02: Tools        (dispatch table, 4 tools)        |
|  s01: Agent Loop   (while True + finish_reason)     |
|                                                     |
+-----------------------------------------------------+

🔗 Section Dependencies

s01 --> s02 --> s03 --> s04 --> s05
                 |               |
                 v               v
                s06 ----------> s07 --> s08
                 |               |
                 v               v
                s09 ----------> s10

s01-s02: Foundation (no dependencies)
s03: Builds on s02 (adds persistence to the tool loop)
s04: Builds on s03 (channels produce InboundMessages for sessions)
s05: Builds on s04 (routes channel messages to agents)
s06: Builds on s03 (uses sessions for context, adds prompt layers)
s07: Builds on s06 (heartbeat uses soul/memory for prompt)
s08: Builds on s07 (heartbeat output flows through delivery queue)
s09: Builds on s03+s06 (reuses ContextGuard for overflow, model config)
s10: Builds on s07 (replaces single Lock with named lane system)

⚡ Quick Start

# 1. Clone and enter
git clone https://github.com/truongpx396/learn-harness-engineering-by-building-mini-openclaw && cd learn-harness-engineering-by-building-mini-openclaw

# 2. Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate        # macOS / Linux
# .venv\Scripts\activate         # Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure
cp .env.example .env
# Edit .env: set OPENAI_API_KEY, MODEL_ID, and OPENAI_BASE_URL

# 5. Run any section
python sessions/en/s01_agent_loop.py

🗺️ Learning Path

Each section adds exactly one new concept. All prior code stays intact:

Phase 1: FOUNDATION     Phase 2: CONNECTIVITY     Phase 3: BRAIN        Phase 4: AUTONOMY       Phase 5: PRODUCTION
+----------------+      +-------------------+     +-----------------+   +-----------------+   +-----------------+
| s01: Loop      |      | s03: Sessions     |     | s06: Intelligence|  | s07: Heartbeat  |   | s09: Resilience |
| s02: Tools     | ---> | s04: Channels     | --> |   soul, memory, | ->|   & Cron        |-->|   & Concurrency |
|                |      | s05: Gateway      |     |   skills, prompt |  | s08: Delivery   |   | s10: Lanes      |
+----------------+      +-------------------+     +-----------------+   +-----------------+   +-----------------+
 while + dispatch        persist + route            personality + recall  proactive + reliable  retry + serialize

📋 Section Details

#	Section	Core Concept	Lines
01	Agent Loop	`while True` + `finish_reason` -- that's an agent	~175
02	Tool Use	Tools = schema dict + handler map. Model picks a name, you look it up	~445
03	Sessions	JSONL: append on write, replay on read. Too big? Summarize old parts	~890
04	Channels	Every platform differs, but they all produce the same `InboundMessage`	~780
05	Gateway	Binding table maps (channel, peer) to agent. Most specific wins	~625
06	Intelligence	System prompt = files on disk. Swap files, change personality	~750
07	Heartbeat & Cron	Timer thread: "should I run?" + queue work alongside user messages	~660
08	Delivery	Write to disk first, then send. Crashes can't lose messages	~870
09	Resilience	3-layer retry onion: auth rotation, overflow compaction, tool-use loop	~1130
10	Concurrency	Named lanes with FIFO queues, generation tracking, Future-based results	~900

📁 Repository Structure

learn-harness-engineering-by-building-a-mini-openclaw/
  README.md              English README
  .env.example           Configuration template
  requirements.txt       Python dependencies
  sessions/              All teaching sessions (code + docs)
    en/                  English
      s01_agent_loop.py  s01_agent_loop.md
      s02_tool_use.py    s02_tool_use.md
      ...                (10 .py + 10 .md)
  workspace/             Shared workspace samples
    SOUL.md  IDENTITY.md  TOOLS.md  USER.md
    HEARTBEAT.md  BOOTSTRAP.md  AGENTS.md  MEMORY.md
    CRON.json
    skills/example-skill/SKILL.md

📦 Prerequisites

Python 3.11+
An OpenAI-compatible API key (e.g. GitHub Models, Azure OpenAI, or any provider)

💻 Running Locally (no cloud API required)

All agents speak the OpenAI chat-completions protocol. Any local server that exposes a compatible endpoint works out of the box — no GPU required, CPU-only inference is supported by all three options below.

Option A — 🖥️ LM Studio

LM Studio provides a GUI for downloading and serving models.

1. Install & load a model

Download and install LM Studio.
In the Discover tab, search for a small instruction-tuned model. Good CPU-friendly choices: Qwen2.5-7B-Instruct, Mistral-7B-Instruct, Phi-3-mini.
Click Download next to your chosen model.

2. Start the local server

Open the Developer tab (</> icon in the left sidebar).
Select your model from the dropdown and click Start Server.
LM Studio listens at http://localhost:1234/v1. Copy the model identifier shown (e.g. lmstudio-community/Qwen2.5-7B-Instruct-GGUF).

3. Configure .env

OPENAI_API_KEY=lm-studio        # any non-empty string works
OPENAI_BASE_URL=http://localhost:1234/v1
MODEL_ID=lmstudio-community/Qwen2.5-7B-Instruct-GGUF

Option B — 🦙 Ollama

Ollama is a lightweight CLI that manages and serves models with a single command.

1. Install Ollama

# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows: download the installer from https://ollama.com/download

2. Pull a model & start the server

ollama pull qwen2.5:7b          # or: mistral, phi3, llama3.2, gemma2:2b …
ollama serve                    # starts at http://localhost:11434

If you ran ollama pull without ollama serve, the server is already running in the background — no extra step needed.

3. Configure .env

OPENAI_API_KEY=ollama           # any non-empty string works
OPENAI_BASE_URL=http://localhost:11434/v1
MODEL_ID=qwen2.5:7b            # must match the name you pulled

Option C — 🌐 GPT4All

GPT4All offers a desktop app with a built-in API server mode.

1. Install GPT4All

Download and install the desktop app from nomic.ai/gpt4all.

2. Download a model & enable the API server

Go to Models → browse and download a model (e.g. Mistral 7B Instruct).
Open Settings → API Server, toggle Enable API Server on.
The server starts at http://localhost:4891/v1.

3. Configure .env

OPENAI_API_KEY=gpt4all          # any non-empty string works
OPENAI_BASE_URL=http://localhost:4891/v1
MODEL_ID=Mistral 7B Instruct   # must match the model name shown in the app

4. Run (same for all options)

python sessions/en/s01_agent_loop.py

Tips for CPU inference

Under 8 GB RAM: use 1.5B–3B models — e.g. Qwen2.5-1.5B-Instruct, Llama-3.2-1B-Instruct.

8 GB–16 GB RAM: use 4-bit quantized 7B–8B models — e.g. Llama-3.1-8B-Instruct (Q4), Mistral-7B-Instruct (Q4).

16 GB+ RAM: standard 7B–13B models work well without extra quantization.

Keep context length at 4096 or lower in your server settings to reduce RAM pressure.

The agents already cap max_tokens at 8096, so small models won't be overwhelmed.

🧩 Dependencies

openai>=1.0.0
python-dotenv>=1.0.0
websockets>=12.0
croniter>=2.0.0
python-telegram-bot>=21.0
httpx>=0.27.0

🔗 Related Projects

learn-claude-code -- A companion teaching repo that builds an agent framework (nano Claude Code) from scratch in 12 progressive sessions. Where learn-harness-engineering-by-building-a-mini-openclaw focuses on gateway routing, channels, and proactive behavior, learn-claude-code dives deep into the agent's internal design: structured planning (TodoManager + nag), context compression (3-layer compact), file-based task persistence with dependency graphs, team coordination (JSONL mailboxes, shutdown/plan-approval FSM), autonomous self-organization, and git worktree isolation for parallel execution. If you want to understand how a production-grade unit agent works inside, start there.

👥 About

Scan with Wechat to fellow us,

or fellow on X: shareAI-Lab

If you found this helpful, let me know by leaving a 👍 or a comment!, or if you think this post could help someone, feel free to share it! Thank you very much! 😃

🤖 Learn Harness Engineering by Building a Mini Claude Code 💻

Truong Phung — Wed, 22 Apr 2026 06:03:42 +0000

Git Repo: truongpx396/learn-harness-engineering-by-building-mini-claude-code

Note: This is a fork of shareAI-lab/learn-claude-code with all agents migrated from the Anthropic SDK to the OpenAI SDK (openai Python package). All agents work with any OpenAI-compatible endpoint — cloud APIs (OpenAI, GitHub Models, Azure OpenAI) or local servers (LM Studio, Ollama, GPT4All).

🧠 Agency Comes from the Model. An Agent Product = Model + Harness.
- 📜 Where Agency Comes From
- ❌ What an Agent Is NOT
- 💡 The Mind Shift: From "Developing Agents" to Developing Harness
- 🔧 What Harness Engineers Actually Do
- 🎓 Why Claude Code — A Masterclass in Harness Engineering
🌌 The Vision: Fill the Universe with Real Agents
⚙️ The Core Pattern
⚠️ Scope (Important)
🚀 Quick Start
- 💻 Running Locally (no cloud API required)
- Option A — 🖥️ LM Studio
- Option B — 🦙 Ollama
- Option C — 🌐 GPT4All
- 🌍 Web Platform
🗺️ Learning Path
🏗️ Architecture
📖 Documentation
🔭 What's Next — from understanding to shipping
Sister Repo: from on-demand sessions to always-on assistant

🧠 Agency Comes from the Model. An Agent Product = Model + Harness.

Before we talk about code, let's get one thing straight.

Agency -- the ability to perceive, reason, and act -- comes from model training, not from external code orchestration. But a working agent product needs both the model and the harness. The model is the driver, the harness is the vehicle. This repo teaches you how to build the vehicle.

📜 Where Agency Comes From

At the core of every agent is a neural network -- a Transformer, an RNN, a learned function -- that has been trained, through billions of gradient updates on action-sequence data, to perceive an environment, reason about goals, and take actions. Agency is never granted by the surrounding code. It is learned by the model during training.

Humans are the best example. A biological neural network shaped by millions of years of evolutionary training, perceiving the world through senses, reasoning through a brain, acting through a body. When DeepMind, OpenAI, or Anthropic say "agent," the core of what they mean is always the same thing: a model that has learned to act, plus the infrastructure that lets it operate in a specific environment.

The proof is written in history:

2013 -- DeepMind DQN plays Atari. A single neural network, receiving only raw pixels and game scores, learned to play 7 Atari 2600 games -- surpassing all prior algorithms and beating human experts on 3 of them. By 2015, the same architecture scaled to 49 games and matched professional human testers, published in Nature. No game-specific rules. No decision trees. One model, learning from experience. That model was the agent.
2019 -- OpenAI Five conquers Dota 2. Five neural networks, having played 45,000 years of Dota 2 against themselves in 10 months, defeated OG -- the reigning TI8 world champions -- 2-0 on a San Francisco livestream. In a subsequent public arena, the AI won 99.4% of 42,729 games against all comers. No scripted strategies. No meta-programmed team coordination. The models learned teamwork, tactics, and real-time adaptation entirely through self-play.
2019 -- DeepMind AlphaStar masters StarCraft II. AlphaStar beat professional players 10-1 in a closed-door match, and later achieved Grandmaster status on European servers -- top 0.15% of 90,000 players. A game with imperfect information, real-time decisions, and a combinatorial action space that dwarfs chess and Go. The agent? A model. Trained. Not scripted.
2019 -- Tencent Jueyu dominates Honor of Kings. Tencent AI Lab's "Jueyu" defeated KPL professional players in a full 5v5 match at the World Champion Cup. In 1v1 mode, pros won only 1 out of 15 games and never survived past 8 minutes. Training intensity: one day equaled 440 human years. By 2021, Jueyu surpassed KPL pros across the full hero pool. No handcrafted matchup tables. No scripted compositions. A model that learned the entire game from scratch through self-play.
2024-2025 -- LLM agents reshape software engineering. Claude, GPT, Gemini -- large language models trained on the entirety of human code and reasoning -- are deployed as coding agents. They read codebases, write implementations, debug failures, coordinate in teams. The architecture is identical to every agent before them: a trained model, placed in an environment, given tools to perceive and act. The only difference is the scale of what they've learned and the generality of the tasks they solve.

Every one of these milestones points to the same fact: agency -- the ability to perceive, reason, and act -- is trained, not coded. But every agent also needed an environment to operate in: the Atari emulator, the Dota 2 client, the StarCraft II engine, the IDE and terminal. The model provides intelligence. The environment provides the action space. Together they form a complete agent.

❌ What an Agent Is NOT

The word "agent" has been hijacked by an entire cottage industry of prompt plumbing.

Drag-and-drop workflow builders. No-code "AI agent" platforms. Prompt-chain orchestration libraries. They all share the same delusion: that wiring together LLM API calls with if-else branches, node graphs, and hardcoded routing logic constitutes "building an agent."

It doesn't. What they build is a Rube Goldberg machine -- an over-engineered, brittle pipeline of procedural rules, with an LLM wedged in as a glorified text-completion node. That is not an agent. That is a shell script with delusions of grandeur.

Prompt plumbing "agents" are the fantasy of programmers who don't train models. They attempt to brute-force intelligence by stacking procedural logic -- massive rule trees, node graphs, chain-of-prompt waterfalls -- and praying that enough glue code will somehow emergently produce autonomous behavior. It won't. You cannot engineer your way to agency. Agency is learned, not programmed.

Those systems are dead on arrival: fragile, unscalable, fundamentally incapable of generalization. They are the modern resurrection of GOFAI (Good Old-Fashioned AI) -- the symbolic rule systems the field abandoned decades ago, now spray-painted with an LLM veneer. Different packaging, same dead end.

💡 The Mind Shift: From "Developing Agents" to Developing Harness

When someone says "I'm developing an agent," they can only mean one of two things:

1. Training the model. Adjusting weights through reinforcement learning, fine-tuning, RLHF, or other gradient-based methods. Collecting task-process data -- the actual sequences of perception, reasoning, and action in real domains -- and using it to shape the model's behavior. This is what DeepMind, OpenAI, Tencent AI Lab, and Anthropic do. This is agent development in the truest sense.

2. Building the harness. Writing the code that gives the model an environment to operate in. This is what most of us do, and it is the focus of this repository.

A harness is everything the agent needs to function in a specific domain:

Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions

    Tools:          file I/O, shell, network, database, browser
    Knowledge:      product docs, domain references, API specs, style guides
    Observation:    git diff, error logs, browser state, sensor data
    Action:         CLI commands, API calls, UI interactions
    Permissions:    sandboxing, approval workflows, trust boundaries

The model decides. The harness executes. The model reasons. The harness provides context. The model is the driver. The harness is the vehicle.

A coding agent's harness is its IDE, terminal, and filesystem access. A farm agent's harness is its sensor array, irrigation controls, and weather data feeds. A hotel agent's harness is its booking system, guest communication channels, and facility management APIs. The agent -- the intelligence, the decision-maker -- is always the model. The harness changes per domain. The agent generalizes across them.

This repo teaches you to build vehicles. Vehicles for coding. But the design patterns generalize to any domain: farm management, hotel operations, manufacturing, logistics, healthcare, education, scientific research. Anywhere a task needs to be perceived, reasoned about, and acted upon -- an agent needs a harness.

🔧 What Harness Engineers Actually Do

If you are reading this repository, you are likely a harness engineer -- and that is a powerful thing to be. Here is your real job:

Implement tools. Give the agent hands. File read/write, shell execution, API calls, browser control, database queries. Each tool is an action the agent can take in its environment. Design them to be atomic, composable, and well-described.
Curate knowledge. Give the agent domain expertise. Product documentation, architectural decision records, style guides, regulatory requirements. Load them on-demand (s05), not upfront. The agent should know what's available and pull what it needs.
Manage context. Give the agent clean memory. Subagent isolation (s04) prevents noise from leaking. Context compression (s06) prevents history from overwhelming. Task systems (s07) persist goals beyond any single conversation.
Control permissions. Give the agent boundaries. Sandbox file access. Require approval for destructive operations. Enforce trust boundaries between the agent and external systems. This is where safety engineering meets harness engineering.
Collect task-process data. Every action sequence the agent executes in your harness is training signal. The perception-reasoning-action traces from real deployments are the raw material for fine-tuning the next generation of agent models. Your harness doesn't just serve the agent -- it can help improve the agent.

You are not writing the intelligence. You are building the world the intelligence inhabits. The quality of that world -- how clearly the agent can perceive, how precisely it can act, how rich its available knowledge is -- directly determines how effectively the intelligence can express itself.

Build great harnesses. The agent will do the rest.

🎓 Why Claude Code — A Masterclass in Harness Engineering

Why does this repository dissect Claude Code specifically?

Because Claude Code is the most elegant and fully-realized agent harness we have seen. Not because of any single clever trick, but because of what it doesn't do: it doesn't try to be the agent. It doesn't impose rigid workflows. It doesn't second-guess the model with elaborate decision trees. It provides the model with tools, knowledge, context management, and permission boundaries -- then gets out of the way.

Look at what Claude Code actually is, stripped to its essence:

Claude Code = one agent loop
            + tools (bash, read, write, edit, glob, grep, browser...)
            + on-demand skill loading
            + context compression
            + subagent spawning
            + task system with dependency graph
            + team coordination with async mailboxes
            + worktree isolation for parallel execution
            + permission governance

That's it. That's the entire architecture. Every component is a harness mechanism -- a piece of the world built for the agent to inhabit. The agent itself? It's Claude. A model. Trained by Anthropic on the full breadth of human reasoning and code. The harness doesn't make Claude smart. Claude is already smart. The harness gives Claude hands, eyes, and a workspace.

This is why Claude Code is the ideal teaching subject: it demonstrates what happens when you trust the model and focus your engineering on the harness. Every session in this repository (s01-s12) reverse-engineers one harness mechanism from Claude Code's architecture. By the end, you understand not just how Claude Code works, but the universal principles of harness engineering that apply to any agent in any domain.

The lesson is not "copy Claude Code." The lesson is: the best agent products are built by engineers who understand that their job is harness, not intelligence.

🌌 The Vision: Fill the Universe with Real Agents

This is not just about coding agents.

Every domain where humans perform complex, multi-step, judgment-intensive work is a domain where agents can operate -- given the right harness. The patterns in this repository are universal:

Estate management agent    = model + property sensors + maintenance tools + tenant comms
Agricultural agent         = model + soil/weather data + irrigation controls + crop knowledge
Hotel operations agent     = model + booking system + guest channels + facility APIs
Medical research agent     = model + literature search + lab instruments + protocol docs
Manufacturing agent        = model + production line sensors + quality controls + logistics
Education agent            = model + curriculum knowledge + student progress + assessment tools

The loop is always the same. The tools change. The knowledge changes. The permissions change. The agent -- the model -- generalizes.

Every harness engineer reading this repository is learning patterns that apply far beyond software engineering. You are learning to build the infrastructure for an intelligent, automated future. Every well-designed harness deployed in a real domain is one more place where an agent can perceive, reason, and act.

First we fill the workshops. Then the farms, the hospitals, the factories. Then the cities. Then the planet.

Bash is all you need. Real agents are all the universe needs.

                    THE AGENT PATTERN
                    =================

    User --> messages[] --> LLM --> response
                                      |
                            msg.tool_calls?
                           /              \
                         yes               no
                          |                 |
                    execute tools       return text
                    append results
                    loop back -------> messages[]


    That's the minimal loop. Every AI agent needs this loop.
    The MODEL decides when to call tools and when to stop.
    The CODE just executes what the model asks for.
    This repo teaches you to build what surrounds this loop --
    the harness that makes the agent effective in a specific domain.

12 progressive sessions, from a simple loop to isolated autonomous execution.
Each session adds one harness mechanism. Each mechanism has one motto.

🔁 s01 "One loop & Bash is all you need" — one tool + one loop = an agent

🛠️ s02 "Adding a tool means adding one handler" — the loop stays the same; new tools register into the dispatch map

📋 s03 "An agent without a plan drifts" — list the steps first, then execute; completion doubles

🪄 s04 "Break big tasks down; each subtask gets a clean context" — subagents use independent messages[], keeping the main conversation clean

📚 s05 "Load knowledge when you need it, not upfront" — inject via tool_result, not the system prompt

🗜️ s06 "Context will fill up; you need a way to make room" — three-layer compression strategy for infinite sessions

📁 s07 "Break big goals into small tasks, order them, persist to disk" — a file-based task graph with dependencies, laying the foundation for multi-agent collaboration

⚡ s08 "Run slow operations in the background; the agent keeps thinking" — daemon threads run commands, inject notifications on completion

👥 s09 "When the task is too big for one, delegate to teammates" — persistent teammates + async mailboxes

📡 s10 "Teammates need shared communication rules" — one request-response pattern drives all negotiation

🤝 s11 "Teammates scan the board and claim tasks themselves" — no need for the lead to assign each one

🌿 s12 "Each works in its own directory, no interference" — tasks manage goals, worktrees manage directories, bound by ID

⚙️ The Core Pattern

def agent_loop(messages):
    while True:
        response = client.chat.completions.create(
            model=MODEL,
            messages=[{"role": "system", "content": SYSTEM}] + messages,
            tools=TOOLS,
            max_completion_tokens=4096,
        )
        msg = response.choices[0].message
        messages.append({"role": "assistant", "content": msg.content,
                         "tool_calls": msg.tool_calls})

        if not msg.tool_calls:
            return

        for tool_call in msg.tool_calls:
            args = json.loads(tool_call.function.arguments)
            output = TOOL_HANDLERS[tool_call.function.name](**args)
            messages.append({"role": "tool",
                             "tool_call_id": tool_call.id,
                             "content": str(output)})

Every session layers one harness mechanism on top of this loop -- without changing the loop itself. The loop belongs to the agent. The mechanisms belong to the harness.

⚠️ Scope (Important)

This repository is a 0->1 learning project for harness engineering -- building the environment that surrounds an agent model.
It intentionally simplifies or omits several production mechanisms:

Full event/hook buses (for example PreToolUse, SessionStart/End, ConfigChange). s12 includes only a minimal append-only lifecycle event stream for teaching.
Rule-based permission governance and trust workflows
Session lifecycle controls (resume/fork) and advanced worktree lifecycle controls
Full MCP runtime details (transport/OAuth/resource subscribe/polling)

Treat the team JSONL mailbox protocol in this repo as a teaching implementation, not a claim about any specific production internals.

🚀 Quick Start

git clone https://github.com/truongpx396/learn-harness-engineering-by-building-mini-claude-code
cd learn-harness-engineering-by-building-mini-claude-code
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env               # Edit .env with your OPENAI_API_KEY

python agents/s01_agent_loop.py       # Start here
python agents/s12_worktree_task_isolation.py  # Full progression endpoint
python agents/s_full.py               # Capstone: all mechanisms combined

💻 Running Locally (no cloud API required)

Option A — 🖥️ LM Studio

LM Studio provides a GUI for downloading and serving models.

1. Install & load a model

Download and install LM Studio.
In the Discover tab, search for a small instruction-tuned model. Good CPU-friendly choices: Qwen2.5-7B-Instruct, Mistral-7B-Instruct, Phi-3-mini.
Click Download next to your chosen model.

2. Start the local server

Open the Developer tab (</> icon in the left sidebar).
Select your model from the dropdown and click Start Server.
LM Studio listens at http://localhost:1234/v1. Copy the model identifier shown (e.g. lmstudio-community/Qwen2.5-7B-Instruct-GGUF).

3. Configure .env

OPENAI_API_KEY=lm-studio        # any non-empty string works
OPENAI_BASE_URL=http://localhost:1234/v1
MODEL=lmstudio-community/Qwen2.5-7B-Instruct-GGUF

Option B — 🦙 Ollama

Ollama is a lightweight CLI that manages and serves models with a single command.

1. Install Ollama

# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows: download the installer from https://ollama.com/download

2. Pull a model & start the server

ollama pull qwen2.5:7b          # or: mistral, phi3, llama3.2, gemma2:2b …
ollama serve                    # starts at http://localhost:11434

If you ran ollama pull without ollama serve, the server is already running in the background — no extra step needed.

3. Configure .env

OPENAI_API_KEY=ollama           # any non-empty string works
OPENAI_BASE_URL=http://localhost:11434/v1
MODEL=qwen2.5:7b                # must match the name you pulled

Option C — 🌐 GPT4All

GPT4All offers a desktop app with a built-in API server mode.

1. Install GPT4All

Download and install the desktop app from nomic.ai/gpt4all.

2. Download a model & enable the API server

Go to Models → browse and download a model (e.g. Mistral 7B Instruct).
Open Settings → API Server, toggle Enable API Server on.
The server starts at http://localhost:4891/v1.

3. Configure .env

OPENAI_API_KEY=gpt4all          # any non-empty string works
OPENAI_BASE_URL=http://localhost:4891/v1
MODEL=Mistral 7B Instruct       # must match the model name shown in the app

4. Run (same for all options)

python agents/s01_agent_loop.py

Tips for CPU inference

Under 8 GB RAM: use 1.5B–3B models — e.g. Qwen2.5-1.5B-Instruct, Llama-3.2-1B-Instruct.

8 GB–16 GB RAM: use 4-bit quantized 7B–8B models — e.g. Llama-3.1-8B-Instruct (Q4), Mistral-7B-Instruct (Q4).

16 GB+ RAM: standard 7B–13B models work well without extra quantization.

Keep context length at 4096 or lower in your server settings to reduce RAM pressure.

The agents already cap max_completion_tokens at 4096, which is compatible with all small models.

🌍 Web Platform

Interactive visualizations, step-through diagrams, source viewer, and documentation.

cd web && npm install && npm run dev   # http://localhost:3000

🗺️ Learning Path

Phase 1: THE LOOP                    Phase 2: PLANNING & KNOWLEDGE
==================                   ==============================
s01  The Agent Loop          [1]     s03  TodoWrite               [5]
     while + tool_calls check            TodoManager + nag reminder
     |                                    |
     +-> s02  Tool Use            [4]     s04  Subagents            [5]
              dispatch map: name->handler     fresh messages[] per child
                                              |
                                         s05  Skills               [5]
                                              SKILL.md via tool_result
                                              |
                                         s06  Context Compact      [5]
                                              3-layer compression

Phase 3: PERSISTENCE                 Phase 4: TEAMS
==================                   =====================
s07  Tasks                   [8]     s09  Agent Teams             [9]
     file-based CRUD + deps graph         teammates + JSONL mailboxes
     |                                    |
s08  Background Tasks        [6]     s10  Team Protocols          [12]
     daemon threads + notify queue        shutdown + plan approval FSM
                                          |
                                     s11  Autonomous Agents       [14]
                                          idle cycle + auto-claim
                                     |
                                     s12  Worktree Isolation      [16]
                                          task coordination + optional isolated execution lanes

                                     [N] = number of tools

🏗️ Architecture

learn-harness-engineering-by-building-mini-claude-code/
|
|-- agents/                        # Python reference implementations (s01-s12 + s_full capstone)
|-- docs/{en}/               # Mental-model-first documentation (3 languages)
|-- web/                           # Interactive learning platform (Next.js)
|-- skills/                        # Skill files for s05
+-- .github/workflows/ci.yml      # CI: typecheck + build

📖 Documentation

Mental-model-first: problem, solution, ASCII diagram, minimal code.
Available in English

Session	Topic	Motto
s01	The Agent Loop	One loop & Bash is all you need
s02	Tool Use	Adding a tool means adding one handler
s03	TodoWrite	An agent without a plan drifts
s04	Subagents	Break big tasks down; each subtask gets a clean context
s05	Skills	Load knowledge when you need it, not upfront
s06	Context Compact	Context will fill up; you need a way to make room
s07	Tasks	Break big goals into small tasks, order them, persist to disk
s08	Background Tasks	Run slow operations in the background; the agent keeps thinking
s09	Agent Teams	When the task is too big for one, delegate to teammates
s10	Team Protocols	Teammates need shared communication rules
s11	Autonomous Agents	Teammates scan the board and claim tasks themselves
s12	Worktree + Task Isolation	Each works in its own directory, no interference

🔭 What's Next — from understanding to shipping

After the 12 sessions you understand how harness engineering works inside out. Two ways to put that knowledge to work:

Kode Agent CLI -- Open-Source Coding Agent CLI

npm i -g @shareai-lab/kode

Skill & LSP support, Windows-ready, pluggable with GLM / MiniMax / DeepSeek and other open models. Install and go.

GitHub: shareAI-lab/Kode-cli

Kode Agent SDK -- Embed Agent Capabilities in Your App

The official Claude Code Agent SDK communicates with a full CLI process under the hood -- each concurrent user means a separate terminal process. Kode SDK is a standalone library with no per-user process overhead, embeddable in backends, browser extensions, embedded devices, or any runtime.

GitHub: shareAI-lab/Kode-agent-sdk

Sister Repo: from on-demand sessions to always-on assistant

The harness this repo teaches is use-and-discard -- open a terminal, give the agent a task, close when done, next session starts blank. That is the Claude Code model.

OpenClaw proved another possibility: on top of the same agent core, two harness mechanisms turn the agent from "poke it to make it move" into "it wakes up every 30 seconds to look for work":

Heartbeat -- every 30s the harness sends the agent a message to check if there is anything to do. Nothing? Go back to sleep. Something? Act immediately.
Cron -- the agent can schedule its own future tasks, executed automatically when the time comes.

Add multi-channel IM routing (WhatsApp / Telegram / Slack / Discord, 13+ platforms), persistent context memory, and a Soul personality system, and the agent goes from a disposable tool to an always-on personal AI assistant.

claw0 is our companion teaching repo that deconstructs these harness mechanisms from scratch:

claw agent = agent core + heartbeat + cron + IM chat + memory + soul

learn-claude-code                   claw0
(agent harness core:                (proactive always-on harness:
 loop, tools, planning,              heartbeat, cron, IM channels,
 teams, worktree isolation)          memory, soul personality)

About

Scan with WeChat to follow us,
or follow on X: shareAI-Lab

Agency comes from the model. The harness makes agency real. Build great harnesses. The model will do the rest.

Bash is all you need. Real agents are all the universe needs.

If you found this helpful, let me know by leaving a 👍 or a comment!, or if you think this post could help someone, feel free to share it! Thank you very much! 😃

🛠️ Harness Engineering — Quick Actionable Guide 🤖

Truong Phung — Mon, 20 Apr 2026 07:09:25 +0000

Distilled from the Learn Harness Engineering course by WalkingLabs, which synthesizes harness engineering theory and practice from OpenAI, Anthropic, and industry practitioners.

The model is smart. The harness makes it reliable.
— A well-harnessed agent spent \$200/6hrs and built a working game. Without a harness, same model spent \$9/20min and produced garbage. The model didn't change. The harness did.

📊 Hard numbers:

📉 SWE-bench Verified top agents: ~50-60% pass rate — on curated tasks with clear descriptions. In real repos? Even lower.
🏗️ OpenAI's million-line experiment: 3 engineers + Codex → ~1,500 PRs over 5 months, ~3.5 PRs/person/day — but only after investing heavily in harness infrastructure.
📄 A team added AGENTS.md to a FastAPI project: same model went from failing all 3 runs to succeeding all 3 runs, with ~60% better context efficiency.
🚀 A TypeScript + React project went from 20% success rate (bare repo) → 100% (full harness). Model never changed.

📑 Table of Contents

🔍 What Is Harness Engineering?
🧩 The 5 Subsystems of a Harness
🚀 Quick Start: Your Minimal Harness (Do This Today)
📐 The 12 Core Principles
- Principle 1: Strong Models ≠ Reliable Execution
- Principle 2: A Harness Is 5 Subsystems, Not a Better Prompt
- Principle 3: The Repo Is the Single Source of Truth
- Principle 4: Split Instructions — Don't Use One Giant File
- Principle 5: Persist Context Across Sessions
- Principle 6: Initialize Before Every Session
- Principle 7: One Feature at a Time — No Overreach (WIP=1)
- Principle 8: Feature Lists Are Harness Primitives
- Principle 9: Don't Let Agents Declare Victory Early
- Principle 10: Only Full-Pipeline Verification Counts
- Principle 11: Make the Agent's Runtime Observable
- Principle 12: Every Session Must Leave a Clean State
🔄 The Agent Session Lifecycle
⚖️ Without Harness vs. With Harness
📝 Additional Templates Worth Adding
🎯 Key Takeaways
🔬 How to Diagnose Harness Quality
📚 References

🔍 What Is Harness Engineering?

Harness engineering is building a complete working environment around an AI coding agent so it produces reliable results. It's NOT about writing better prompts. It's about designing the system the model operates inside.

You → give task → Agent reads harness files → Agent executes
                                                |
                                      harness governs every step:
                                      ├── Instructions: what to do, in what order
                                      ├── Scope: one feature at a time
                                      ├── State: progress log, feature list, git history
                                      ├── Verification: tests, lint, type-check
                                      └── Lifecycle: init at start, clean state at end
                                                |
                                                v
                                      Agent stops ONLY when
                                      verification passes

🧩 The 5 Subsystems of a Harness

Every effective harness has exactly five parts:

#	Subsystem	Job	Key Files
1	📋 Instructions	Tell the agent what to do, in what order, what to read first	`AGENTS.md`, `CLAUDE.md`, `docs/`
2	💾 State	Track what's done, in-progress, and next. Persisted to disk so the next session picks up exactly where the last left off	`claude-progress.md`, `feature_list.json`, `git log`
3	✅ Verification	Only passing tests count as evidence. Agent cannot declare victory without proof	tests, lint, type-check, smoke runs
4	🎯 Scope	Constrain agent to ONE feature at a time. No overreach. No half-finishing three things	feature boundaries, definition of done
5	🔄 Session Lifecycle	Initialize at start. Clean up at end. Leave a clean restart path	`init.sh`, handoff notes, clean commits

🚀 Quick Start: Your Minimal Harness (Do This Today)

Drop these 4 files into your project root:

YOUR PROJECT ROOT
├── AGENTS.md              ← the agent's operating manual
├── init.sh                ← runs install + verify + health check
├── feature_list.json      ← what features exist, which are done
├── claude-progress.md     ← what happened each session
└── src/                   ← your actual code

1. `AGENTS.md` — The Operating Manual

# Agent Instructions

## Before Starting Any Work
1. Run `./init.sh` to verify environment health
2. Read `claude-progress.md` for context from last session
3. Read `feature_list.json` to see what's done and what's next
4. Check `git log --oneline -10` for recent changes

## Rules
- Work on exactly ONE feature at a time
- Never declare "done" without passing tests
- Run the full test suite before committing
- Update `claude-progress.md` after every session
- Update `feature_list.json` when a feature status changes
- Commit only when the project is in a clean, resumable state

## Verification Checklist
- [ ] All tests pass
- [ ] Linter passes
- [ ] Type-check passes
- [ ] Feature works as specified

2. `init.sh` — Environment Health Check

#!/bin/bash
set -e
echo "=== Installing dependencies ==="
npm install
echo "=== Running tests ==="
npm test
echo "=== Type checking ==="
npx tsc --noEmit
echo "=== Environment healthy ==="

3. `feature_list.json` — Machine-Readable Scope

{
  "features": [
    { "id": "F001", "name": "User login", "status": "done", "tests": "src/auth.test.ts" },
    { "id": "F002", "name": "Document import", "status": "in-progress", "tests": "src/import.test.ts" },
    { "id": "F003", "name": "Search", "status": "not-started", "tests": null }
  ]
}

4. `claude-progress.md` — Session Memory

# Progress Log

## Session 3 — 2026-04-20
- Completed: F001 (user login) — all tests passing
- In progress: F002 (document import) — parser done, validation pending
- Blocked: none
- Next session should: finish F002 validation logic, then run full test suite

📐 The 12 Core Principles

Principle 1: Strong Models ≠ Reliable Execution

Problem: Models ace benchmarks but fail on real multi-file engineering tasks.
Why: Real tasks need multi-step coordination, not one-shot answers. Agents fail at five specific layers:

Task specification — vague requirements → agent guesses wrong
Context provision — implicit conventions not written down → agent violates them
Execution environment — missing deps, wrong versions → agent wastes context on setup
Verification feedback — no tests → agent says "done" when it's not
State management — no progress tracking → next session starts from zero

Action: When things fail, fix the harness first, not the model. Attribute every failure to one of these five layers. One AGENTS.md file might be more effective than upgrading to a more expensive model.

Diagnostic Loop: Execute → observe failure → attribute to a specific harness layer → fix that layer → re-execute. After a few rounds, your harness gets stronger and agent performance stabilizes.

Principle 2: A Harness Is 5 Subsystems, Not a Better Prompt

Problem: People think "better prompt = better results."
Why: Prompts don't persist state, verify work, or control scope.
Action: Implement all 5 subsystems: instructions, state, verification, scope, lifecycle.

Real data: A team added subsystems one at a time to a TypeScript + React project:

Stage 1 (bare repo): 20% success rate
Stage 2 (+AGENTS.md): 60%
Stage 3 (+verification commands): 80%
Stage 4 (+progress files): 80-100%

The feedback/verification subsystem has the lowest investment and highest ROI. Start there.

Constrain, don't micromanage. Use executable rules, not step-by-step instructions. OpenAI: "enforce invariants, don't micromanage implementation."

Harness debt is real. Harness rots like code does. Audit regularly — remove outdated rules, update stale docs.

Principle 3: The Repo Is the Single Source of Truth

Problem: If the agent can't see it in the repo, it doesn't exist. Your Slack history, Jira tickets, Confluence pages, verbal agreements — the agent sees none of it.
Why: Agents don't remember conversations. They read files. They can't ask a colleague.
Action: Put everything the agent needs INTO the repo: instructions, progress, feature definitions, docs.

Cold-Start Test — open a fresh agent session (no verbal context) and see if it can answer:

What is this system?
How is it organized?
How do I run it?
How do I verify it?
What's the current progress?

If it can't answer → your repo has blind spots. Where the map is blank, the agent guesses — and guessing creates bugs.

ACID Principles for Agent State:

Atomicity — Each logical operation gets one git commit. If it fails midway, git stash to roll back.
Consistency — All tests pass, lint reports zero errors before committing. Inconsistent states don't get committed.
Isolation — Multiple agents use separate progress files or git branches.
Durability — Cross-session knowledge must be persisted to files. What's only in memory doesn't count.

Place knowledge near code. A 50-line ARCHITECTURE.md in src/api/ is more useful than a 500-page Confluence doc nobody maintains.

Principle 4: Split Instructions — Don't Use One Giant File

Problem: One massive instruction file overwhelms the agent's context. A team's AGENTS.md grew from 50 → 600 lines. Their agent success rate dropped from 72% to 45%.
Why: Three killers:

Lost in the Middle Effect (Liu et al., 2023): LLMs use info in the middle of long texts far less effectively than at the beginning or end. A critical rule at line 300 of 600 will likely be ignored.
Context budget eaten alive: A 600-line file consumes 10-20K tokens before the agent even starts working.
Priority conflicts: Hard constraints, soft guidelines, and historical notes all look identical. The agent can't distinguish.

Action: Keep AGENTS.md at 50-200 lines as a routing file. Split details into topic docs:

AGENTS.md (50-200 lines — overview + hard constraints + links)
├── docs/api-patterns.md        ← read when adding endpoints
├── docs/database-rules.md      ← read when modifying DB operations  
├── docs/testing-standards.md   ← reference when writing tests
└── docs/deployment.md          ← read only for deployment tasks

Rules for the entry file:

Put critical rules at the top or bottom, never the middle
Max 15 non-negotiable hard constraints
Every instruction should have: a source (why), applicability (when), and expiry (when to remove)
Audit regularly — delete outdated rules like you delete unused dependencies

Result: After splitting, a team's success rate went from 45% → 72%, and security constraint compliance went from 60% → 95%.

Principle 5: Persist Context Across Sessions

Problem: Session 2 starts fresh. Agent has no memory of Session 1. Tasks over 30 minutes see failure rates spike sharply without state.
Why: Without persisted state, the agent re-does work, reverses deliberate decisions, or drifts from requirements like a game of telephone.

Context Anxiety (discovered by Anthropic): When agents sense context is running low, they rush — skipping verification, choosing simple solutions over correct ones. Like guessing on remaining exam questions when time is almost up.

Action: Use three continuity artifacts:

claude-progress.md — What's done, what's in progress, what's blocked, next steps
DECISIONS.md — Why option B was chosen over A, with date and reasoning. Prevents the next session from reversing deliberate choices.
Git commits as checkpoints — Commit after each atomic unit of work with clear messages explaining what and why.

Key metric: Rebuild Cost — how long a new session takes to reach an executable state. Good harnesses: ~3 minutes. Bad harnesses: 15-20 minutes.

Real data: A 12-feature blog system over 5 sessions:

Without progress files: 58% features completed, 43% hidden defect rate
With progress files: 100% features completed, 8% hidden defect rate, rebuild time reduced ~78%

WITHOUT STATE                        WITH STATE
Session 1: does work                 Session 1: does work, writes progress
Session 2: starts from zero          Session 2: reads progress, continues
Result: rework & drift               Result: steady forward progress

Principle 6: Initialize Before Every Session

Problem: Agent starts coding in a broken environment (missing deps, failing tests). Code written before the test framework is configured = code without verification.
Why: Initialization and implementation have different goals. Mixing them = doing both poorly. Anthropic's data: dedicated initialization phase → 31% higher feature completion in multi-session scenarios.
Action: Treat initialization as a separate phase. The first session does ONLY initialization — no feature code.

Bootstrap Contract — initialization is complete when four conditions are met:

✅ Can start (make setup succeeds)
✅ Can test (at least one example test passes)
✅ Can see progress (task breakdown file exists)
✅ Can pick up next steps (progress file is readable)

Warm start >> Cold start. Use project templates to preset standard structure. Starting from a template is 10x better than starting from an empty directory.

Time invested in initialization is fully recovered in the next 3-4 sessions.

Principle 7: One Feature at a Time — No Overreach (WIP=1)

Problem: Agents try to do 3 things at once, finish none of them properly. Context capacity C divided by k tasks = each task gets C/k attention. When that drops below minimum, nothing finishes.
Why: Overreach and under-finish amplify each other. More code written ≠ more features completed — Anthropic found they're negatively correlated. Agents using "small next step" (WIP=1) show 37% higher task completion.
Action: Enforce WIP=1 (Work-in-Progress Limit from Kanban). Write it explicitly in AGENTS.md:

## Work Rules
- Work on one feature at a time
- Only start the next feature after the current one passes end-to-end verification
- Don't "also refactor" feature B while implementing feature A

Real data: REST API with 8 features:

Unconstrained: 5 features activated, ~800 lines across 12 files, 20% end-to-end pass → 37.5% completion by session 3
WIP=1: 1 feature at a time, ~200 lines across 4 files, 100% pass → 87.5% completion by session 4

"Do less but finish" always beats "do more but leave half-done."

Principle 8: Feature Lists Are Harness Primitives

Problem: Vague scope = vague results. "Shopping cart mostly done" — what does "mostly" mean? Which tests passed? Nobody knows.
Why: Feature lists aren't memos — they're the backbone of the harness. The scheduler, verifier, and handoff reporter all depend on them.
Action: Every feature entry must be a triple: (behavior description, verification command, current state)

{
  "id": "F03",
  "behavior": "POST /cart/items with {product_id, quantity} returns 201",
  "verification": "curl -X POST localhost:3000/api/cart/items -d '{\"product_id\":1}' | jq .status",
  "state": "not_started"
}

State machine — four states, controlled by the harness:

not_started → active (agent picks it up)
active → passing (only when verification command succeeds — pass-state gating)
active → blocked (dependency issue)
passing is irreversible — once verified, it stays verified

Granularity rule: Each feature should be completable in one session. "User can add items to cart" = good. "Implement the shopping cart" = too broad. "Create the name field on the Cart model" = too narrow.

Result: Structured feature lists show 45% higher completion rate than free-form tracking, with zero duplicate implementations.

Principle 9: Don't Let Agents Declare Victory Early

Problem: Agent says "done!" but tests fail, edge cases are broken, or code doesn't compile. Anthropic found that agents confidently praise their own work — you must separate "the person who does the work" from "the person who checks the work."
Why: Verification Gap = the gap between the agent's confidence and actual correctness. This is the #1 failure mode.
Action: Write an explicit Definition of Done for every task. Not "add a search feature" but:

Completion criteria:
- New endpoint GET /api/search?q=xxx
- Supports pagination, default 20 items
- Results include highlighted snippets
- All new code passes pytest
- Type checking passes (mypy --strict)

"Done" = verification passes. "The code looks fine" does NOT count. curl returns 201 DOES count.

Principle 10: Only Full-Pipeline Verification Counts

Problem: Agent runs one unit test. Claims everything works.
Why: Partial verification misses integration issues, type errors, and regressions.
Action: Require the full pipeline: tests + lint + type-check + build + smoke run. All must pass.

Principle 11: Make the Agent's Runtime Observable

Problem: You can't fix what you can't see. Missing observability wastes 30-50% of session time on redundant diagnosis.
Why: Without observability: agents can't distinguish "correct" from "looks correct," retries become blind guesses, and evaluation becomes subjective.
Action: Build two layers of observability:

Layer 1 — Runtime signals: Application lifecycle, feature path execution, errors with full context. The harness collects these automatically — don't rely on the agent to log its own actions.

Layer 2 — Process observability:

Sprint contracts — before each task, define: what to change, what NOT to change, pass criteria, exclusions
Evaluator rubrics — turn "is it good?" into structured scoring:

Dimension	A	B	C	D
Code correctness	All tests pass	Main flow passes	Partial pass	Build fails
Test coverage	Main + edge cases	Main flow only	Skeleton only	No tests

Real data: A "dark mode" task — without observability: 3-4 blind retries, 45 minutes. With sprint contract + rubric: 1 iteration, 15 minutes. 3x efficiency.

Principle 12: Every Session Must Leave a Clean State

Problem: Agent leaves half-committed code, broken tests, uncommitted changes. "Clean up later" = never clean up.
Why: Entropy grows by default (Lehman's Laws). Without cleanup, a 12-week project degrades:

	Week 1	Week 12 (no cleanup)	Week 12 (with cleanup)
Build pass rate	100%	68%	97%
Test pass rate	100%	61%	95%
Session startup	5 min	60+ min	9 min

Action: Session completion = task passes verification AND clean state check passes. Five dimensions:

## Session Exit Checklist
- [ ] Build passes (npm run build)
- [ ] All tests pass (npm test)  
- [ ] Feature list + progress updated
- [ ] No debug code remaining (console.log, debugger, TODO)
- [ ] Standard startup path works (npm run dev)

Quality Document — maintain an active scorecard for each module (A/B/C/D). New sessions read it and know where to prioritize.

Periodically simplify the harness. As models improve, some constraints become unnecessary overhead. Monthly: disable one harness component, run benchmarks. If results don't degrade → remove it permanently.

🔄 The Agent Session Lifecycle (Follow This Every Time)

START
  1. Agent reads AGENTS.md
  2. Agent runs init.sh (install, verify, health check)
  3. Agent reads claude-progress.md (what happened last time)
  4. Agent reads feature_list.json (what's done, what's next)
  5. Agent checks git log (recent changes)

SELECT
  6. Agent picks exactly ONE unfinished feature
  7. Agent works ONLY on that feature

EXECUTE
  8. Agent implements the feature
  9. Agent runs verification (tests, lint, type-check)
  10. If verification fails → fix and re-run
  11. If verification passes → record evidence

WRAP UP
  12. Agent updates claude-progress.md
  13. Agent updates feature_list.json
  14. Agent records what's still broken or unverified
  15. Agent commits (only when safe to resume)
  16. Agent leaves clean restart path for next session

⚖️ Without Harness vs. With Harness

	Without Harness	With Harness
🟡 Session start	Agent starts fresh, no context	Agent reads progress, picks up where it left off
🟡 Scope	Agent does random things	Agent works on one specific feature
🟡 "Done"	Agent says "looks good"	Tests pass, lint clean, types check
🟡 Session end	Half-committed mess	Clean state, progress logged, ready for next session
🟡 Your role	Rescue & cleanup	Review & approve
🟡 Result	You spend more time fixing than if you did it yourself	Agent does the work, you verify the result

📝 Additional Templates Worth Adding

`DECISIONS.md` — Prevent Next Session From Reversing Your Choices

# Design Decisions

## 2026-04-15: Use Redis for user preferences caching
- Reason: High read frequency (every API call), small data size
- Rejected: PostgreSQL materialized view (high change frequency)
- Constraint: Cache TTL of 5 minutes, active invalidation on write

## 2026-04-18: Use Vitest over Jest
- Reason: Native ESM support, faster execution
- Constraint: All test files use .test.ts extension

Sprint Contract — For Complex Tasks

# Sprint Contract: Dark Mode Support

## Scope
- Modify the theme toggle component
- Update global CSS variables
- Add dark mode tests

## Verification Standards
- Visual regression tests pass
- Main flow E2E tests pass
- No flash of unstyled content (FOUC)

## Exclusions
- NOT handling print styles
- NOT handling third-party component dark mode

Richer `feature_list.json` — With Verification Evidence

{
  "features": [
    {
      "id": "F01",
      "behavior": "POST /api/register with {email, password} returns 201",
      "verification": "curl -X POST /api/register -d '{\"email\":\"test@example.com\"}' | jq .status",
      "state": "passing",
      "evidence": "commit abc123, test output log"
    },
    {
      "id": "F02",
      "behavior": "GET /api/search?q=xxx returns paginated results (default 20)",
      "verification": "pytest tests/test_search.py -x",
      "state": "active",
      "evidence": null
    }
  ]
}

🎯 Key Takeaways

🔧 The harness doesn't make the model smarter — it makes its output reliable
📂 Everything the agent needs must live in the repo (if it can't see it, it doesn't exist)
🎯 One feature at a time — scope is the most underrated lever
✅ Never trust "done" without verification evidence — tests must pass
🧹 Every session must leave a clean state — the next session's success depends on it
💾 State must persist to disk — memory dies between sessions, files don't
🔄 Initialize before work, verify during work, clean up after work — this is the lifecycle
🔍 When things fail, fix the harness first — attribute failures to one of five layers, fix that layer, re-run
1️⃣ WIP=1 — finish one feature before starting the next. Less code, more completed features
⚠️ Harness debt is real — audit and simplify regularly. Rules that helped last month may be unnecessary overhead today
🏁 "Do less but finish" beats "do more but leave half-done" — always

🔬 How to Diagnose Harness Quality

Isometric Model Control: Keep the model fixed. Remove harness components one at a time. Measure which removal causes the biggest performance drop. That's your bottleneck — focus your effort there.

Remove this...	If performance drops significantly...
AGENTS.md	Your instructions are critical
Verification commands	Your feedback loop is carrying the weight
Progress files	Your state management is essential
Feature list	Your scope control is doing the heavy lifting
init.sh	Your initialization is preventing cascading failures

📚 References

- GitHub Repo

If you found this helpful, let me know by leaving a 👍 or a comment!, or if you think this post could help someone, feel free to share it! Thank you very much! 😃

🏗️ 📐 Harness Engineering: The Emerging Discipline of Making AI Agents Reliable 🤖

Truong Phung — Thu, 16 Apr 2026 08:21:39 +0000

Truong Phung

Apr 15

🏗️ 📐 Harness Engineering: The Emerging Discipline of Making AI Agents Reliable 🤖

#ai #agents #llm #programming

Comments

20 min read

🏗️ 📐 Harness Engineering: The Emerging Discipline of Making AI Agents Reliable 🤖

Truong Phung — Wed, 15 Apr 2026 08:44:19 +0000

A comprehensive guide to the practice of shaping the environment around AI agents so they can work dependably — based on references from the Awesome Harness Engineering collection.

What Is Harness Engineering?
Why It Matters Now
The Core Equation: Agent = Model + Harness
Foundations & Key Mental Models
Context Engineering: The Working Memory Budget
Constraints, Guardrails & Safe Autonomy
Specs, Agent Files & Workflow Design
Evals & Observability
Runtimes, Harnesses & Reference Implementations
Benchmarks: Measuring Harness Quality
Practical Playbook: Engineering Your Own Harness
The Future of Harness Engineering
Conclusion
References & Further Reading

1. What Is Harness Engineering?

Harness engineering is the practice of designing, building, and iterating on the environment, tooling, constraints, and feedback loops that surround an AI agent — everything that isn't the model itself. The term gained widespread traction in early 2026, popularized by field reports from OpenAI, Anthropic, LangChain, Thoughtworks, and HumanLayer, all converging on the same insight: the reliability of an AI agent depends less on the model and more on the system wrapped around it.

As LangChain's Vivek Trivedy crystallized it:

Agent = Model + Harness. If you're not the model, you're the harness.

A harness includes:

System prompts — the instructions that shape the agent's persona and constraints
Tools, skills, and MCP servers — capabilities the agent can invoke
Bundled infrastructure — filesystem, sandboxes, browsers, observability stacks
Orchestration logic — sub-agent spawning, handoffs, model routing
Hooks and middleware — deterministic control flow for compaction, continuation, lint checks, and verification
Memory and state management — progress files, git history, structured knowledge bases

A raw model is not an agent. It becomes one only when a harness gives it state, tool execution, feedback loops, and enforceable constraints. Harness engineering is the discipline of making all of that work well.

2. Why It Matters Now

The "Skill Issue" Realization

As HumanLayer argued, teams that blame weak agent results on model limitations are usually wrong. After hundreds of agent sessions across dozens of projects, the pattern is consistent:

It's not a model problem. It's a configuration problem.

Every time a team instinctively says "GPT-6 will fix it" or "we just need better instruction-following," the real fix is almost always in the harness — better context management, smarter tool selection, proper verification loops, or cleaner handoff artifacts.

The OpenAI Proof Point

OpenAI's flagship field report provided dramatic evidence. A three-person engineering team built and shipped an internal product with zero manually-written code — roughly a million lines across application logic, tests, CI, documentation, and tooling — all generated by Codex agents. The team averaged 3.5 merged PRs per engineer per day, and Codex runs regularly worked autonomously for six hours or more.

The key insight was that early progress was slower than expected — not because Codex was incapable, but because the environment was underspecified. The primary job of human engineers became enabling agents to do useful work: building the harness.

"Because the only way to make progress was to get Codex to do the work, human engineers always stepped into the task and asked: 'what capability is missing, and how do we make it both legible and enforceable for the agent?'"

Harness Changes Move Benchmarks

LangChain demonstrated that harness changes alone can significantly improve benchmark performance — moving their coding agent from Top 30 to Top 5 on Terminal-Bench 2.0 by only changing the harness, not the model. Anthropic showed that infrastructure configuration can move coding benchmark scores by more than many leaderboard gaps. The implication is profound: benchmarks often measure harness quality as much as — or more than — model quality.

3. The Core Equation: Agent = Model + Harness

LangChain's Anatomy of an Agent Harness provides the clearest decomposition. Working backwards from what models cannot do natively reveals why each harness component exists:

What We Want	What Models Can't Do Natively	Harness Solution
Persistent memory	Maintain durable state across interactions	Filesystem, git, progress files, AGENTS.md
Autonomous problem-solving	Execute arbitrary code	Bash tool, code execution sandboxes
Real-time knowledge	Access information beyond training cutoff	Web search, MCP tools, Context7
Safe operation	Understand risk boundaries	Sandboxes, allow-lists, network isolation
Long-horizon coherence	Work across multiple context windows	Compaction, Ralph Loops, planning files
Self-verification	Know if their work is correct	Test runners, browser automation, linters

The filesystem emerges as the most foundational harness primitive because it unlocks everything else: agents get a workspace, work can be incrementally persisted, and multiple agents can coordinate through shared files. Git adds versioning so agents can track work, rollback errors, and branch experiments.

4. Foundations & Key Mental Models

4.1 Feedforward and Feedback (Thoughtworks)

Birgitta Böckeler's framework at Thoughtworks provides the most rigorous mental model for harness engineering. She frames it through two control mechanisms:

Guides (feedforward controls) — anticipate the agent's behavior and steer it before it acts. They increase the probability of good results on the first attempt. Examples: AGENTS.md files, architecture documentation, skills, coding conventions, reference applications.
Sensors (feedback controls) — observe after the agent acts and help it self-correct. Most powerful when they produce signals optimized for LLM consumption. Examples: linters with custom error messages, test suites, code review agents, browser screenshots.

Without guides, the agent keeps repeating mistakes. Without sensors, the agent encodes rules but never finds out whether they worked. A good harness requires both.

4.2 Computational vs. Inferential

Each control can be either:

Computational — deterministic and fast, run by the CPU. Tests, linters, type checkers, structural analysis. Milliseconds to seconds; results are reliable.
Inferential — semantic analysis, AI code review, "LLM as judge." Slower, more expensive, non-deterministic — but capable of richer judgment.

Control	Direction	Type	Example
Coding conventions	Feedforward	Inferential	AGENTS.md, Skills
Structural tests	Feedback	Computational	ArchUnit tests checking module boundaries
Code review agent	Feedback	Inferential	A review skill using a strong model
Bootstrap scripts	Feedforward	Both	Skill with instructions and a bootstrap script
Code mods	Feedforward	Computational	OpenRewrite recipes

4.3 The Cybernetic Governor

The harness acts as a cybernetic governor — combining feedforward and feedback to regulate the codebase toward its desired state. Böckeler identifies three regulation dimensions:

Maintainability harness — internal code quality (linters, complexity checks, coverage). The most mature category with extensive pre-existing tooling.
Architecture fitness harness — system characteristics (performance, observability, security). Essentially architectural fitness functions.
Behaviour harness — functional correctness. The hardest category: how do we verify that the application does what we need? This remains the elephant in the room.

4.4 The Three Pillars (Thoughtworks)

Thoughtworks frames harness work into three pillars:

Context engineering — managing what the agent knows and when
Architectural constraints — enforcing invariants mechanically
Garbage collection — fighting entropy and drift continuously

4.5 Control–Agency–Runtime (CAR) Decomposition

An academic position paper proposes treating the harness layer as a first-class research object with three dimensions:

Control — constraints, guardrails, permissions
Agency — planning, decision-making, self-evaluation
Runtime — execution environment, tools, infrastructure

5. Context Engineering: The Working Memory Budget

Context engineering is the practice of managing the agent's context window as a working memory budget rather than a dumping ground. It is arguably the most critical aspect of harness engineering.

5.1 The One Big File Anti-Pattern

OpenAI learned the hard way that a monolithic AGENTS.md doesn't scale:

Context is a scarce resource. A giant instruction file crowds out the task, the code, and the relevant docs.

Too much guidance becomes non-guidance. When everything is "important," nothing is.

It rots instantly. A monolithic manual turns into a graveyard of stale rules.

It's hard to verify. A single blob doesn't lend itself to mechanical checks.

Their solution: treat AGENTS.md as a table of contents (~100 lines) that points to deeper sources of truth in a structured docs/ directory. This enables progressive disclosure — agents start with a small, stable entry point and are taught where to look next.

5.2 Progressive Disclosure

Progressive disclosure is the principle that agents should only receive specific instructions, knowledge, or tools when they actually need them. Loading everything upfront pushes the agent into what HumanLayer calls "the dumb zone" — where context window fill degrades performance even on simple tasks.

Chroma's research on context rot provides empirical backing: models perform measurably worse at longer context lengths, and degradation is steeper when there's low semantic similarity between the query and the relevant information in context.

Skills solve this: they're activated on demand, bringing in focused knowledge only when needed.

5.3 Context-Efficient Backpressure

HumanLayer's backpressure philosophy is essential: verification mechanisms must be context-efficient. Running a full test suite after every change floods the context window with thousands of lines of passing tests. The agent loses track of its actual task.

The rule: success is silent, only failures produce output. Swallow the output of passing checks and only surface errors.

5.4 Sub-Agents as Context Firewalls

Sub-agents provide context isolation — each gets a fresh, small, high-relevance context window for its task, and only the condensed result flows back to the parent. This is far more powerful than simply making context windows bigger:

"A bigger context window doesn't make the model better at finding the needle — it just makes the haystack bigger."

Effective sub-agent tasks: codebase exploration, grep/search operations, tracing information flow, research tasks — anything with a straightforward question and simple answer that requires many intermediate tool calls.

5.5 Lessons from Manus

Manus' playbook contributed specific techniques: KV-cache locality optimization, tool masking, filesystem memory, and keeping useful failures in-context while discarding noise.

5.6 OpenHands Context Condensation

OpenHands' approach to bounded conversation memory preserves goals, progress, critical files, and failing tests while condensing everything else — keeping long-running coding sessions efficient without losing essential state.

6. Constraints, Guardrails & Safe Autonomy

6.1 Enforcing Invariants, Not Micromanaging

OpenAI's approach is instructive: enforce boundaries centrally, allow autonomy locally. They require Codex to parse data shapes at the boundary (parse, don't validate), but don't prescribe how. Each business domain follows a fixed layered architecture (Types → Config → Repo → Service → Runtime → UI) with strictly validated dependency directions enforced by custom linters and structural tests — all Codex-generated.

"This is the kind of architecture you usually postpone until you have hundreds of engineers. With coding agents, it's an early prerequisite: the constraints are what allows speed without decay."

Custom linter error messages are written to inject remediation instructions into agent context — a positive form of prompt injection that guides self-correction.

6.2 Sandboxing and Controlled Execution

Anthropic's work on sandboxing focuses on reducing approval friction without losing control. Rather than prompting humans for every action, better sandboxing and policy design allow agents to work more autonomously while staying within safe boundaries.

MCP-based code execution gives agents controlled execution power through explicit, inspectable tool boundaries — making it clear what the agent can and cannot do.

6.3 Tool Design for Safety

Anthropic's guidance on writing tools for agents emphasizes that tool interfaces should be easy for models to call correctly and safely. Poorly designed tools lead to misuse; well-designed tools guide the agent toward correct behavior.

6.4 Prompt Injection Defense

OpenHands' practical guide covers confirmation mode, analyzers, sandboxing, and hard policies for reducing prompt-injection risk. This is especially important given that MCP server tool descriptions are injected into system prompts — never connect to one you don't trust.

6.5 Quality Checks in the Loop

Rather than relying on after-the-fact manual review, Thoughtworks advocates moving quality checks into the agent's own loop. Anchoring agents to reference applications constrains output with concrete exemplars. The question for humans becomes not "how do I review every line?" but "where should I strengthen the harness?"

7. Specs, Agent Files & Workflow Design

7.1 AGENTS.md and Agent Files

AGENTS.md is a lightweight open format for repo-local instructions that tell agents how to work inside a codebase. A related effort, agent.md, pursues machine-readable agent instructions across projects and tools.

The key insights from practitioners:

Keep it concise — under 60 lines is a good target. HumanLayer's CLAUDE.md is under 60 lines.
Avoid auto-generating it — LLM-generated agent files actually hurt performance while costing 20%+ more tokens.
Don't include directory listings — agents discover repository structure on their own just fine.
Use progressive disclosure — point to deeper resources rather than inlining everything.
Make instructions universally applicable — avoid conditional rules that confuse the model.

7.2 Spec-Driven Development

GitHub's Spec Kit enables spec-driven development where agents execute against explicit product and engineering specifications. Thoughtworks' analysis explains why strong specs make AI-assisted delivery more dependable: they give agents unambiguous goals to work toward.

7.3 The 12-Factor Agent

HumanLayer's 12-Factor Agents establishes operating principles for production agents:

Explicit prompts over implicit behavior
State ownership — agents manage their own state
Clean pause-resume behavior
Context discipline
Reproducible workflows

The companion 12-Factor AgentOps extends these principles to operations.

7.4 Feature Lists for Long-Running Work

Anthropic's approach to long-running agents uses an initializer agent that generates a comprehensive feature list (200+ features for a web app), all initially marked as "failing." Subsequent coding agents work through features one at a time, marking them as passing only after verification. This prevents two critical failure modes:

The one-shot attempt — the agent tries to build everything at once, runs out of context mid-implementation, and leaves a broken state.
Premature victory — the agent sees existing progress and declares the job done.

The feature list uses JSON rather than Markdown because models are less likely to inappropriately modify structured JSON files.

8. Evals & Observability

8.1 Why Evals Are Hard for Agents

Anthropic's guidance on demystifying evals highlights the fundamental challenge: agents have many possible trajectories to success or failure. A single task can be completed through vastly different tool-call sequences, making traditional input-output evaluation insufficient.

8.2 Eval Taxonomies

OpenAI's eval guide introduces turning agent traces into repeatable evals with JSONL logs and deterministic checks. LangChain's breakdown distinguishes:

Single-step evals — does one tool call produce the right result?
Full-run evals — does the complete task get solved?
Multi-turn evals — does the agent handle conversations and evolving goals?

8.3 Trace Grading

OpenAI's trace grading enables grading agent traces directly — especially helpful for long multi-step tasks where the final output alone doesn't reveal whether the agent's process was sound.

8.4 Verification Stacks

OpenHands' layered verification uses trajectory critics trained on production traces for reranking, early stopping, and review-time quality control. This goes beyond simple pass/fail testing to assess the quality of the agent's reasoning process.

8.5 Skill-Level Evals

OpenHands' playbook emphasizes measuring whether a specific skill actually helps using:

Bounded tasks
Deterministic verifiers
No-skill baselines
Trace review

8.6 Infrastructure Noise

Anthropic's research on infrastructure noise shows that runtime configuration can move coding benchmark scores by more than many leaderboard gaps — meaning that benchmark results may reflect infrastructure choices more than model intelligence.

9. Runtimes, Harnesses & Reference Implementations

9.1 The Framework/Runtime/Harness Distinction

LangChain's decomposition clarifies what belongs where:

Framework — reusable abstractions for building agents (LangGraph, CrewAI)
Runtime — execution infrastructure (sandboxes, state management, scheduling)
Harness — the task-specific configuration and environment around a particular agent deployment

9.2 Notable Implementations

Project	Description
SWE-agent	Mature research coding agent with inspectable harness, prompt, tools, and environment design
Claude Agent SDK	Production-oriented SDK with sessions, tools, and orchestration
deepagents	LangChain's open-source project for building deeper, longer-running agents with middleware and harness patterns
Citadel	Harness for Claude Code and Codex with isolated worktrees, multi-agent coordination, and persisted memory
AgentKit	TypeScript toolkit for building durable, workflow-aware agents on event-driven infrastructure
Harbor	Generalized harness for evaluating and improving agents at scale
Harness Evolver	Claude Code plugin that autonomously evolves agent harnesses using multi-agent proposers and evaluation
SWE-ReX	Sandboxed code execution infrastructure for AI agents
Uni-CLI	Universal CLI connecting agents to 134 sites via 711 declarative YAML pipelines with self-repair loop

9.3 Skills Ecosystem

skills.sh is a community marketplace for discovering, sharing, and installing reusable AI agent skills across runtimes like Claude Code — making harness capabilities portable and composable. However, caution is warranted: skill registries have already been caught distributing malicious skills, so treat them like npm install random-package and read what you're installing.

10. Benchmarks: Measuring Harness Quality

Benchmarks are especially useful when you want to compare harness quality, not just model quality. They stress context handling, tool calling, environment control, verification logic, and the runtime scaffolding around the model.

10.1 Software Engineering Benchmarks

Benchmark	Focus
SWE-bench Verified	Real GitHub issues and tests; makes harness choices around retrieval, patching, and validation highly visible
Terminal-Bench	Terminal-native agents in shells and filesystems; especially useful for comparing coding-agent harnesses
EvoClaw	Dependent milestone sequences from real repo history; surfaces regression accumulation

10.2 Web & Browser Benchmarks

Benchmark	Focus
WebArena	Self-hostable web environment for evaluating autonomous agents
VisualWebArena	Multimodal web agents with image and screenshot inputs
BrowserGym	Reproducible framework comparing harnesses across multiple web benchmarks
WorkArena	Enterprise-style web workflows

10.3 General & Multi-Domain Benchmarks

Benchmark	Focus
AgentBench	Cross-environment: OS, databases, knowledge graphs, web browsing
GAIA	General AI assistant tasks comparing harness-level choices
OSWorld	Real computer-use across Ubuntu, Windows, macOS
AppWorld	Interactive coding agents with state-based and execution-based unit tests
ClawBench	Search, reasoning, coding, safety, and multi-turn conversation

10.4 MCP-Specific Benchmarks

Benchmark	Focus
MCP Bench	Tool accuracy, latency, and token use across MCP server types
MCPMark	Stress-testing on real-world MCP tasks (Notion, GitHub, Postgres)
OSWorld-MCP	Real-world computer tasks using Model Context Protocol

10.5 Leaderboards

Leaderboard	Focus
Agent Arena	ELO-style ratings from head-to-head agent battles
HAL	Holistic agent evaluation with reliability, cost, and broad task coverage
Galileo Agent Leaderboard	LLM agents on task completion and tool calling across business domains

11. Practical Playbook: Engineering Your Own Harness

Drawing from all the sources in the Awesome Harness Engineering collection, here is a practical playbook for building an effective harness.

Step 1: Start with Agent Files (But Keep Them Lean)

Create a concise AGENTS.md or CLAUDE.md at the root of your repository:

Keep it under 60 lines
Treat it as a table of contents, not an encyclopedia
Include: build commands, test commands, key conventions, project structure pointers
Exclude: directory listings, conditional rules, auto-generated content
Point to deeper docs/ for architectural decisions, design principles, and domain knowledge

Step 2: Set Up Computational Feedback Loops

These are your highest-leverage, lowest-cost sensors:

Type checking — catches structural errors deterministically
Linting with custom error messages that include remediation instructions
Fast test suites — run a targeted subset, not the full suite
Structural/architectural tests — enforce module boundaries and dependency directions

Critical rule: success is silent. Swallow output from passing checks; only surface errors to the agent.

Step 3: Add Verification Tools

Give the agent ways to verify its own work as a human would:

Browser automation (Puppeteer, Playwright) for end-to-end UI verification
Screenshot capture so the agent can visually inspect results
Observability stack — expose logs via LogQL, metrics via PromQL, traces via TraceQL
Dev server per worktree — isolate each agent's environment

Step 4: Implement Hooks for Control Flow

Use harness hooks to create deterministic checkpoints:

Pre-stop hooks: run formatter + type checker before the agent finishes; re-engage on failure
Notification hooks: alert humans when the agent needs attention
Approval hooks: auto-approve safe operations, deny dangerous ones (e.g., migrations)
Integration hooks: create PRs, post to Slack, set up preview environments

Step 5: Use Sub-Agents for Context Control

Don't use sub-agents as "frontend engineer" or "backend engineer" personas — that doesn't work. Use them as context firewalls:

Delegate research, grep, and exploration to sub-agents
Use cheaper models (Sonnet, Haiku) for sub-agents; expensive models (Opus) for the parent
Return condensed results with source citations (filepath:line format)
Keep the parent thread in the "smart zone" with minimal context pollution

Step 6: Enforce Architecture Mechanically

Define layered architecture with fixed dependency directions
Write custom linters (the agent can write them!)
Add structural tests that check invariants on every commit
Encode "taste" as rules: structured logging, naming conventions, file size limits

Step 7: Manage Long-Running Work

For tasks spanning multiple context windows:

Use an initializer agent to set up the environment: init.sh, progress file, feature list, initial git commit
Each subsequent coding agent reads progress, works on one feature, commits, and writes a summary
Always start a session by reading progress files and running a basic health check
Always end a session with a clean, mergeable state

Step 8: Fight Entropy Continuously

OpenAI's "garbage collection" pattern:

Encode golden principles directly in the repository
Run recurring background agents that scan for deviations
Open targeted, small refactoring PRs that can be reviewed in under a minute
Track quality grades per domain and per architectural layer
Treat technical debt like a high-interest loan: pay it down daily

Step 9: Make Knowledge Repository-Local

Everything the agent needs must be in the repo:

Slack discussions about architecture? Encode them as markdown
Design decisions? Write ADRs
Onboarding knowledge? Put it in structured docs
Knowledge in people's heads? Doesn't exist for the agent

"From the agent's point of view, anything it can't access in-context while running effectively doesn't exist."

Step 10: Iterate Based on Failures

The most important meta-principle:

"Anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again." — Mitchell Hashimoto

Don't design the ideal harness upfront. Bias toward shipping. Add configuration only when the agent actually fails. Throw away things that don't help. Distribute battle-tested configurations via repository-level config.

12. The Future of Harness Engineering

Model-Harness Co-Evolution

Today's frontier coding agents (Claude Code, Codex) are post-trained with models and harnesses in the loop. This creates a feedback cycle where useful primitives are discovered, added to the harness, and then used when training the next generation of models. But this co-evolution has interesting side effects: models can become over-fitted to their training harness, performing worse in alternative harness configurations.

Harnessability as a Design Criterion

Not every codebase is equally amenable to harnessing. Thoughtworks introduces "harnessability" — the structural properties that make a codebase governable:

Strongly typed languages naturally have type-checking as a sensor
Clearly definable module boundaries afford architectural constraint rules
Mature frameworks abstract away details agents don't need to worry about

Greenfield teams can bake harnessability in from day one. Legacy teams face the harder problem: the harness is most needed where it is hardest to build.

Harness Templates

Enterprises have a few common service topologies (CRUD APIs, event processors, data dashboards). These may evolve into harness templates — bundles of guides and sensors pre-configured for a topology. Teams may start picking tech stacks partly based on what harnesses are already available.

Autonomous Harness Evolution

Projects like Harness Evolver point toward a future where agents autonomously improve their own harnesses using multi-agent proposers, evaluation-backed selection, and git worktree isolation.

Open Problems

How do we keep a harness coherent as it grows, with guides and sensors in sync?
How far can we trust agents to make trade-offs when instructions conflict?
If sensors never fire, is that high quality or inadequate detection?
How do we evaluate harness coverage similar to code coverage?
How does architectural coherence evolve over years in a fully agent-generated system?
Can we generalize these findings beyond coding to scientific research, financial modeling, and other domains?

13. Conclusion

Harness engineering represents a fundamental shift in how we think about AI-assisted software development. The discipline acknowledges a counterintuitive truth: the model is usually fine; the problem is the system around it.

The implications reshape what it means to be a software engineer:

Engineers become environment designers — specifying intent, building feedback loops, and shaping constraints rather than writing code directly.
Architecture becomes an early prerequisite — not a luxury for large teams, but a necessity for agent reliability.
Repository knowledge becomes the system of record — everything the agent needs must be versioned, discoverable, and mechanically verifiable.
Quality is enforced mechanically — once encoded, standards apply everywhere at once, at every hour.
Entropy is managed continuously — technical debt is treated as a high-interest loan, paid down daily by background agents.

As Thoughtworks' Böckeler frames it: building this outer harness is emerging as an ongoing engineering practice, not a one-time configuration. Harnesses externalize what human developer experience brings to the table — conventions, quality intuitions, architectural judgment, organizational alignment — making it explicit, verifiable, and continuously enforceable.

The field is young, evolving rapidly, and full of open questions. But one thing is clear: the teams that invest in harness engineering — shaping the environment around their agents — will get dramatically better results than those waiting for the next model release to solve their problems.

"Building software still demands discipline, but the discipline shows up more in the scaffolding rather than the code." — OpenAI

14. References & Further Reading

Workflow Design

AGENTS.md — Open Standard
GitHub Spec Kit — GitHub
12 Factor Agents — HumanLayer
12-Factor AgentOps — AgentOps

Evals & Observability

Testing Agent Skills Systematically with Evals — OpenAI
Demystifying Evals for AI Agents — Anthropic
Evaluating Deep Agents — LangChain
Improving Deep Agents with harness engineering — LangChain

Courses

walkinglabs/learn-harness-engineering — A project-based course on making Codex and Claude Code more reliable

Curated Collection

walkinglabs/awesome-harness-engineering — The comprehensive, community-maintained list that informed this article

This article synthesizes insights from the Awesome Harness Engineering collection — a curated list maintained by Walking Labs. All referenced works are credited to their original authors and organizations.

If you found this helpful, let me know by leaving a 👍 or a comment!, or if you think this post could help someone, feel free to share it! Thank you very much! 😃

DEV Community: Truong Phung

📘 Spec Kit vs. Superpowers ⚡ — A Comprehensive Comparison & Practical Guide to Combining Both 🚀

📑 Table of Contents

⚡ TL;DR

1. 🧠 Philosophy

📘 Spec Kit — "The spec is the source of truth"

🦸 Superpowers — "The workflow is the source of truth"

🔀 The philosophical split

2. 🔄 Workflow & Mental Model

📘 Spec Kit's 7-step workflow

🦸 Superpowers' 7 workflow stages

🎯 Key contrast

3. 🏗️ Architecture & Primary Unit

📘 Spec Kit — Slash commands + templates

🦸 Superpowers — Skills + agents + plugins

🎬 Trigger model — the deepest difference

4. 🤖 Agent / Tool Compatibility

5. 📦 Installation & Distribution

📘 Spec Kit

🦸 Superpowers

6. 🧩 Customization & Extensibility

📘 Spec Kit

🦸 Superpowers

🔍 Comparison

7. 🌟 What Each Does Especially Well

📘 Spec Kit shines when…

🦸 Superpowers shines when…

8. ⚖️ Tradeoffs & Limitations

📘 Spec Kit

🦸 Superpowers

9. 🤝 How They Could Coexist

9a. 🛠️ The Best Way to Combine Both — A Practical Guide

⚙️ One-time setup (do this once per machine + once per repo)

🔁 The per-feature loop (the one you actually use)

📜 The two non-obvious rules that make this combo work

📋 One-line prompt template for the execution handoff

📏 When to scale down (don't over-engineer small work)

🚫 Anti-patterns to avoid

✅ A 60-second mental checklist before starting any feature

10. 🧭 Quick Decision Guide

11. 📊 At-a-Glance Summary

🚀 Claude Code: From Zero to Hero 🤖

Table of contents

🌱 Part 1 — Zero

1. 🤖 What Claude Code actually is

2. 📦 Install and first run

3. 🎯 Your first real task

4. ⌨️ The interface

Key commands (type these at the prompt)

Permission modes (the single most useful thing to understand)

Interrupting

🔧 Part 2 — Apprentice

5. 📄 CLAUDE.md

What to put in it

What to leave out

Layering

Rules of thumb

6. 🔐 Permissions

Pattern rules

Personal vs team

The golden rule

7. 🗺️ Plan mode

When to skip plan mode

When to always use plan mode

8. 🧹 Context hygiene

Rules

Signs your context is polluted

⚡ Part 3 — Journeyman

9. ⚡ Slash commands

Minimal example

With arguments

Frontmatter (optional)

Gotchas

Slash command vs skill vs subagent

10. 🤝 Subagents

Defining a subagent

Built-in agent types

When to use a subagent

When NOT to use a subagent

11. 💡 Skills

Using `--debug`