Building Your Own Harness in Claude Code

Claude Code from Anthropic is a powerful agentic coding tool that runs in your terminal, IDE, or other environments. It lets Claude explore codebases, edit files, run commands, and handle complex tasks autonomously. But raw power alone often leads to context bloat, goal drift, inconsistent quality, or stalled sessions.

The secret to unlocking reliable, production-grade performance isn’t a better model prompt—it’s the harness: the custom architecture of files, rules, tools, memory systems, and workflows you build around Claude. Think of it as the operating environment that turns a capable LLM into a disciplined, self-improving development teammate.

This guide walks you through building your own harness from scratch. It’s practical, step-by-step, and focused on what actually works in real projects.

What Exactly Is a Harness?

A harness is the collection of persistent configurations and extensions in your project (and optionally your home directory) that shape how Claude behaves:

• Instructions and rules that load every session.
• Skills for reusable workflows.
• Agents/subagents for specialized roles.
• Hooks for lifecycle events (e.g., pre/post tool use, verification).
• Settings for permissions, models, and environment.
• Memory and state for continuity across sessions.
• MCP integrations for external tools.

It lives primarily in a .claude/ directory (project-level, committable to git) and ~/.claude/ (global, personal). The harness doesn’t change much between runs—the agentic loop (reason → tool use → observe → repeat) runs inside it.

Good harnesses solve context management, enforce quality gates, enable specialization, and improve over time.

Step 1: Set Up the Foundation

Start in your project root:

1. Create the core files (or let /init help bootstrap):
   • CLAUDE.md (or at root): High-level project instructions, coding standards, architecture overview, workflow rules. Keep it concise (~200-300 lines max).
   • .claude/settings.json: Permissions, default models, hooks, env vars.
   • .claude/settings.local.json (gitignored): Personal tweaks.

Example minimal CLAUDE.md structure:

# Project Context
[Brief description, tech stack, goals]

## Coding Standards
- ...

## Workflow Rules
1. Always explore first.
2. Plan with testable criteria.
3. Verify with tests/builds.
...

Use claude in your terminal and run /init or similar commands to analyze the codebase and generate starters.

Step 2: Add Modular Rules

Don’t cram everything into CLAUDE.md. Use .claude/rules/ for topic-specific, optionally path-gated instructions:

• code-style.md
• testing.md
• security.md
• api-conventions.md

These load conditionally or on demand, saving context. Path-gating lets rules apply only to certain directories (e.g., frontend vs. backend).

Step 3: Build Reusable Skills

Skills are self-contained workflows defined in .claude/skills/<name>/SKILL.md. They support progressive disclosure (load details only when needed) and can be invoked manually or automatically.

Examples:

• Security review
• Deployment pipeline
• Refactoring patterns
• Documentation generation

A skill file typically includes:

• Description and triggers
• Step-by-step instructions
• Input/output expectations
• References or templates

Skills make your harness composable and reduce repetition.

Step 4: Introduce Specialized Agents and Subagents

Define personas in .claude/agents/*.md for roles like:

• Code reviewer
• QA tester
• Architect
• Researcher

Use Claude’s agent team or subagent features to orchestrate them. For complex tasks, an orchestrator agent can spawn subagents with fresh contexts, preventing bloat in the main session.

This is especially powerful for large codebases or multi-step projects.

Step 5: Implement Hooks for Control and Self-Improvement

Hooks run at key points in the agentic loop (e.g., PreToolUse, PostToolUse, Stop).

Common uses:

• Security scanning (block dangerous commands)
• Auto-formatting/linting after edits
• Verification gates (e.g., run tests before commit)
• Logging or memory updates

Hooks turn reactive behavior into proactive guardrails.

Step 6: Configure Settings and MCP

In settings.json:

• Model preferences (Opus for complex reasoning, Sonnet/Haiku for speed)
• Tool permissions and sandboxing
• Hook references
• Environment variables

Add .mcp.json for Model Context Protocol servers to integrate external services (databases, design tools, issue trackers, browsers, etc.). This extends Claude beyond your local filesystem.

Step 7: Memory and State Management

Claude Code maintains session history and auto-memory (e.g., MEMORY.md or project-specific files). Design your harness to:

• Summarize learnings at session end
• Load relevant memory at start
• Use rules or skills to query/update state

This creates continuity and self-evolution.

Advanced: Dynamic Workflows and Plugins

• Workflows: JavaScript files in .claude/workflows/ for spawning parallel agents, dynamic routing, or pipelines.
• Plugins: Extend via the marketplace or custom (e.g., harness builders like those from the community).
• Headless mode (claude -p): Integrate into scripts or CI for automated tasks.

For very large projects, use worktrees, scoped rules per subdirectory, and layered CLAUDE.md files.

Best Practices for a Robust Harness

• Context discipline: Track usage, compact aggressively, prefer summaries/subagents over full file reads.
• Verification loops: Always give Claude runnable checks (tests, builds, linters).
• Explore → Plan → Execute → Review → Ship: Separate phases explicitly.
• Start small: Build one pillar (e.g., rules + basic skills), iterate based on real usage.
• Team sharing: Commit project-level files; keep personal ones in ~/.claude/.
• Security first: Sandbox, secret scanning, command allowlists.
• Measure and evolve: Use hooks to log performance; refine based on patterns that fail or succeed.

Why Build Your Own?

Pre-built plugins and templates (e.g., team architecture factories) are great starters, but a custom harness tailored to your domain, stack, and team norms multiplies effectiveness far beyond defaults. It reduces drift, enforces consistency, reuses knowledge, and scales with your codebase.

The harness beats the model because it provides structure, memory, and boundaries that pure prompting can’t.

Getting Started Today

1. Install Claude Code if you haven’t.
2. In a test project: claude, explore /help, run init commands.
3. Create CLAUDE.md + basic rules.
4. Add one skill and one hook.
5. Iterate on a small task and refine.

Over time, your harness becomes a living part of your codebase—an AI development layer that grows smarter with every commit.

The future of coding isn’t just faster models; it’s better environments around them. Build your harness, and watch Claude become an indispensable teammate.

Happy building! Experiment, share what works in your setup, and keep refining.

Made with 💻 in India