What is learn-claude-code? A Guide to AI Agent Harness Engineering

Mar 18, 2026

I spent months building AI agents the wrong way.

I created elaborate prompt chains. I built drag-and-drop workflow builders. I constructed node graphs that looked impressive but produced mediocre results. Every time my agent failed, I added another prompt rule. Another constraint. Another “if this, then that” branch.

The codebase grew. The complexity exploded. The agent stayed dumb.

Then I found learn-claude-code, and it fundamentally changed how I think about building AI systems.

The Problem With “Prompt Plumbing”

Here’s what most of us do when building agents:

┌─────────────────────────────────────────────────────────┐
│                  The Wrong Approach                      │
├─────────────────────────────────────────────────────────┤
│                                                          │
│    [User Input] ──► [Prompt #1] ──► [Prompt #2]         │
│                           │               │              │
│                           ▼               ▼              │
│                      [Check A?]      [Check B?]         │
│                        │   │            │   │            │
│                      Yes   No         Yes   No          │
│                        │    │           │    │           │
│                        ▼    ▼           ▼    ▼           │
│                     [...]  [...]      [...]  [...]       │
│                                                          │
│         Result: Spaghetti prompts, fragile logic         │
└─────────────────────────────────────────────────────────┘

I called this “prompt plumbing” - routing inputs through an ever-growing maze of conditional prompts. The more branches I added, the more edge cases I discovered, and the more prompts I needed.

The model wasn’t thinking. It was executing my brittle decision tree.

The Mental Model Shift

learn-claude-code taught me something different:

An agent is a model. Not a framework. Not a prompt chain. Not a drag-and-drop workflow.

The model IS the agent. Your job as a developer is to build the harness - the tools, context, knowledge, and permissions that let the model express its intelligence.

┌─────────────────────────────────────────────────────────┐
│                   The Right Approach                     │
├─────────────────────────────────────────────────────────┤
│                                                          │
│                    ┌──────────────┐                     │
│                    │     MODEL    │                     │
│                    │  (The Agent) │                     │
│                    └──────┬───────┘                     │
│                           │                              │
│         ┌─────────────────┼─────────────────┐          │
│         │                 │                 │          │
│         ▼                 ▼                 ▼          │
│    ┌─────────┐      ┌──────────┐     ┌──────────┐     │
│    │  TOOLS  │      │ KNOWLEDGE │     │PERMISSIONS│    │
│    │         │      │          │     │          │      │
│    │ - Read  │      │ - Docs   │     │ - File   │     │
│    │ - Write │      │ - Skills │     │ - Network│     │
│    │ - Bash  │      │ - Context│     │ - Delete │     │
│    └─────────┘      └──────────┘     └──────────┘      │
│                                                          │
│         Result: Model thinks, harness enables           │
└─────────────────────────────────────────────────────────┘

This shift is profound. Instead of engineering the thinking (which the model already does well), you engineer the environment in which the thinking happens.

What is Harness Engineering?

The harness has five components:

Tools - What can the agent do? (Read files, write files, run bash, search)
Knowledge - What does the agent know? (Docs, skills, context files)
Observation - What can the agent see? (Error messages, file contents)
Action Interfaces - How does the agent interact? (Function calling, tool use)
Permissions - What is the agent allowed to do? (Sandbox limits, approval gates)

When I stopped adding prompts and started improving the harness, my agents got smarter. Not because I made the model smarter, but because I gave it better tools and better information.

The 12-Session Learning Path

learn-claude-code is structured as 12 progressive Python sessions. Each adds one harness mechanism with one motto.

Let me show you the progression:

Session  │  Concept           │  What You Learn
────────┼────────────────────┼─────────────────────────────
s01     │  Agent Loop        │  The fundamental loop pattern
s02     │  Tool Calling       │  How tools work
s03     │  Context Loading    │  Injecting knowledge
s04     │  Error Handling     │  Graceful failure
s05     │  Multi-Turn Memory  │  Conversation persistence
s06     │  System Prompts     │  Shaping behavior
s07     │  Permission Gates   │  Safety boundaries
s08     │  Parallel Tools     │  Concurrent execution
s09     │  Specialized Agents │  Domain expertise
s10     │  Agent Teams        │  Collaboration patterns
s11     │  Task Orchestration │  Workflow management
s12     │  Worktree Isolation │  Sandboxed execution

The beauty is in the progression. You start with a simple loop and build up to autonomous teams with isolated execution environments.

The Core Pattern: The Agent Loop

Everything starts with the agent loop. Here’s the fundamental pattern from s01:

def agent_loop(messages: list):
    while True:
        # The model thinks
        response = client.messages.create(
            model=MODEL,
            system=SYSTEM,
            messages=messages,
            tools=TOOLS,
            max_tokens=8000,
        )

        # Remember what the model said
        messages.append({"role": "assistant", "content": response.content})

        # If done thinking, return
        if response.stop_reason != "tool_use":
            return

        # Execute tools, get results, continue loop
        tool_results = execute_tools(response.content)
        messages.append({"role": "user", "content": tool_results})

That’s it. That’s the core of every AI agent.

The loop is:

Model receives messages
Model thinks and decides what to do
If done, return
If tool use, execute and add results
Repeat

All the complexity - the context injection, the permission checks, the parallel execution - it all builds on this simple foundation.

What I Built Wrong (And How I Fixed It)

Let me show you a concrete example. I was building a code review agent. My first attempt used a chain of prompts:

def review_code(code):
    # Step 1: Check for bugs
    bug_analysis = prompt_model(f"Find bugs in: {code}")

    # Step 2: Check for security issues
    security_analysis = prompt_model(f"Check security: {code}")

    # Step 3: Check for style issues
    style_analysis = prompt_model(f"Check style: {code}")

    # Step 4: Combine results
    if bug_analysis.severity == "high":
        return prompt_model(f"Suggest fixes for: {bug_analysis}")
    elif security_analysis.risk == "critical":
        return prompt_model(f"Suggest security fixes: {security_analysis}")
    # ... more branches

This approach had problems:

The model couldn’t explore the codebase - it only saw what I passed
The logic was brittle - every new check required more branching
The context was limited - no access to docs, tests, or related files

After learning harness engineering, I rebuilt it:

def review_code_with_harness():
    # Define tools the agent can use
    TOOLS = [
        read_file_tool,
        search_codebase_tool,
        check_docs_tool,
        write_suggestion_tool,
    ]

    # Load relevant knowledge
    SYSTEM = load_system_prompt("code-reviewer-skill.md")

    # The model decides what to do
    return agent_loop(
        messages=[{"role": "user", "content": "Review the current changes"}],
        tools=TOOLS,
        system=SYSTEM,
    )

The difference? The model now:

Reads any file it wants (not just what I pass)
Searches the codebase for patterns
Checks documentation for context
Writes suggestions directly

The harness provides capabilities. The model decides how to use them.

The Skill Injection Pattern

One of the most powerful harness techniques is skill injection. Instead of trying to encode expertise in prompts, you inject entire skill files.

I created a skill file for my code reviewer:

# Code Reviewer Skill

## Principles
- Focus on correctness first, then performance, then style
- Check for security issues in all input handling
- Verify error handling covers edge cases

## Common Patterns to Check
1. Missing null checks before dereferencing
2. SQL injection in query construction
3. Unhandled promise rejections
4. Missing error context in logs

## Output Format
1. Severity (critical/high/medium/low)
2. Issue description
3. File location
4. Suggested fix with code

This gets loaded into the system prompt. Now the model has my expertise encoded as knowledge, not as a rigid workflow.

Why This Matters Beyond Coding Agents

The harness engineering philosophy applies to any agent domain:

Domain          │  Tools                │  Knowledge
────────────────┼───────────────────────┼────────────────────────
Research Agent   │  Web search, PDF read │  Research methodology
Customer Support │  Ticket system, CRM   │  Product docs, policies
Data Analyst     │  SQL, Python, charts  │  Business metrics, schema
DevOps Agent     │  Kubectl, Terraform   │  Infrastructure docs

The pattern is always:

Give the model domain-appropriate tools
Inject domain knowledge via skills
Set appropriate permission boundaries
Let the model think

Getting Started

If you want to learn this approach:

Clone the repository:

git clone https://github.com/shareAI-lab/learn-claude-code

Start with s01 - the agent loop

cd learn-claude-code/agents
python s01_agent_loop.py

Progress through each session, adding one concept at a time
Build something - a code reviewer, a research agent, a data analyst

The sessions are designed to be read in order. Each builds on the previous. By session 12, you’ll understand how to build autonomous agent teams with isolated execution environments.

Key Takeaways

After working through learn-claude-code, here’s what I internalized:

Stop engineering prompts - Start engineering tools, knowledge, and permissions
The model is the agent - Your harness lets it express its intelligence
Simple loop, powerful harness - The pattern is simple; the power is in the harness
Skills > prompts - Inject knowledge as files, not instructions
Progressive complexity - Start simple, add mechanisms one at a time

The repository is available in English, Chinese, and Japanese. Each session has a Python implementation and documentation that explains the mental model first.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!