Pricing & Purchasing

Prices accurate as of March 2026

1. Go to claude.ai and create a free account with your email.
2. Install Claude Code: winget install Anthropic.ClaudeCode or download from claude.ai/download
3. Run claude in a terminal. It will prompt you to log in — use your claude.ai account.
4. You're on the free tier. Try it. If you hit limits, upgrade.

You do not need a credit card to start. The free tier is real — it's just rate-limited.

Snapshot as of March 2026. Verify at claude.ai/upgrade before relying on fine details.

Important: All Claude surfaces (claude.ai website, Claude Desktop, Claude Code CLI) share the same usage pool. If you burn through messages on the website, you have fewer for coding.

"Our company has 60 people. What's the monthly bill?"
At the community-reported ~$60/seat/month for standard seats: 60 × $60 = $3,600/month in seat fees, plus API usage (token costs) on top. If you're deploying premium seats with Claude Code access (~$150/seat), it's 60 × $150 = $9,000/month before usage. Budget $5,000–$15,000/month all-in for a 60-person shop doing active AI coding. Annual commitment, so expect to negotiate. These are community estimates — Anthropic's actual quote could be higher or lower.

"Our company has 3 people. Can we get Enterprise?"
Probably not at standard terms. Reports suggest a minimum floor of 20 seats. However: you can sometimes buy up — paying for 20 seats even if only 3 people use them. That would cost ~$1,200–$3,000/month for 3 actual users, which is absurd value math. For a 3-person team, Team plan ($150/user/month for premium Claude Code seats = $450/month) is almost certainly the right answer. You get Claude Code access without the enterprise overhead and minimum commitment.

"What if I'm willing to pay as if we had 70 people just to get Enterprise features?"
Call Anthropic sales and ask directly. Some vendors will take your money. You'd be looking at 70 × $60 = $4,200+/month for features a 3-person team doesn't need (SSO, SCIM, audit logs are organizational plumbing). The honest answer: don't. Max 20× ($200/month) gets you more coding throughput per dollar than any Enterprise arrangement would for a solo or small team.

Two categories — one genuinely useful to anyone working on large projects, one only useful to organizations managing many people. Don't conflate them.

(Anthropic's words, translated into something honest)

"Extended context model" is not a different AI. It is the same Opus 4.6 or Sonnet 4.6, with the reading window expanded from 267 pages to 1,333 pages. Same IQ. Five times more Awareness. The difference between seeing a chapter and seeing the whole book.

A medium project — say 100 source files — is already beyond what Pro can hold at once. Max fits it comfortably. For very large codebases, neither plan holds everything; you manage context deliberately with /compact and targeted file reads rather than loading the whole project.

Tokens are like gas. You can measure gas two ways: by how far it gets you (miles per gallon) or by what it costs per gallon. Both are useful. Tokens work the same way:

• How far it gets you: One token ≈ 4 characters ≈ ¾ of a word. A typical message exchange (your prompt + Claude's response + any files read) might burn 5,000–20,000 tokens. A complex coding session reading many files might burn 50,000+ tokens in a single exchange. The Pro plan's 45-message window is like a tank of gas — enough for the commute, not enough for a road trip.
• What it costs: On the subscription plans, tokens are pre-paid in your monthly fee. On the API (direct access for building apps), you pay per million tokens — input tokens cost $3/million, output tokens cost $15/million on Sonnet. A 50,000-token session would cost roughly $0.15–$0.75 depending on the mix.

When you run out of tokens in a window, Claude slows down or stops until the window resets (every 5 hours). That's the tank hitting empty.

Two Ways Claude Charges for Tokens — and Why It Matters

There are two completely different ways to pay for Claude, and they get confused constantly:

Way 1: Subscription (Pro, Max) — You pay a flat monthly fee. Tokens are included inside your message budget. You don't see a token bill. You just hit a wall when you've sent too many messages in a 5-hour window, then wait for it to reset. This is what most people use. Simple.

Way 2: API / Pay-per-token — You get an API key from Anthropic and pay directly for every token consumed, with no subscription. The per-token rates in the table above are what you pay. This is for developers building applications that use Claude — a company baking Claude into their own product, not a developer using Claude as a coding tool. You'd wire your app to Claude's API and get billed for token consumption each month.

Enterprise uses Way 2 on top of a seat fee. The seat fee (~$60–$150/user/month) buys access and organizational features (audit logs, SSO, etc.). But every message your team sends still burns tokens, billed at per-token rates on top of that seat fee. That's what "token consumption billed separately" means in the Enterprise section — it's the same tokens as above, just billed directly instead of wrapped in a message budget.

If you're a developer using Claude Code to write code: use a subscription (Pro or Max). You never need to think about API keys or per-token rates. Those are for building products, not for using Claude as a tool.

Think of it like fidelity in images. A single photograph can be ultra-high-resolution — every pixel tiny, every detail captured. That's high IQ. A movie has thousands of frames, covering far more ground — but each individual frame may be lower resolution than a still photo. That's high Awareness.

You want both — but they are separate dials. When you pay more for AI, you might be buying a sharper photograph (better reasoning per frame), more frames (larger context window), or both. A high-IQ model on a small plan sees 267 pages with brilliant resolution. The same model on a Max plan sees 1,333 pages — five times the movie, same sharpness per frame.

Editorial teaching model — not benchmark scores. IQ numbers are estimated shorthand for relative reasoning quality (Opus 4.6 = 100 baseline), not official measurements. Awareness numbers are calculated from published token limits and are factual.  ■ IQ = editorial estimate  ■ Awareness = official fact

• Use /compact regularly. Compressing conversation history frees context and reduces token burn on subsequent messages.
• Switch to Haiku for simple tasks. Renaming a variable doesn't need Opus. Use /model to downshift.
• Keep CLAUDE.md concise. It's loaded every session. A bloated CLAUDE.md burns tokens on every single message.
• Don't read files unnecessarily. If you ask Claude to "look at everything," it will. Be specific about which files matter.
• Start fresh sessions for new tasks. A clean session has an empty context window. Carrying forward a 100-message conversation history into a new task wastes tokens.

Life of a Token

You type a message. Claude responds. What actually happened? The answer crosses your keyboard, your network card, the public internet, a data center, dozens of GPU chips, and back again. The same piece of data gets called something different at every stop. This page traces the complete journey.

The KV cache for your session lives in GPU VRAM for the entire duration of your session. Every token you have sent and every token Claude has generated stays in VRAM as the KV cache. That is how Claude remembers what you discussed 100 messages ago. It is all right there in GPU memory on a server in a data center.

• When you /compact — the KV cache is partially freed. Anthropic literally reclaims GPU memory. This is why /compact reduces server costs, not just your Awareness.
• When your session ends — the KV cache is freed immediately. Gone. That GPU VRAM is reallocated to someone else's session within milliseconds.
• Prompt caching — Anthropic can retain frequently-used KV entries (like your CLAUDE.md or system prompt) in VRAM between sessions. Cache read tokens cost $0.30/M instead of $3/M because the expensive compute already happened once and the vectors are still in memory.

Different models run on different hardware pools. Opus 4.6 is a larger model than Sonnet 4.6. Larger model means:

• More parameters means more GPUs needed just to hold the model weights
• Larger KV cache per token means more VRAM consumed per active session
• Each Opus session ties up significantly more hardware than a Sonnet session

Anthropic allocates separate GPU capacity per model. The Opus pool fills up first during peak demand because it is smaller. Fewer Opus GPUs exist because fewer users need it and it costs more per session to serve. When you saw "Opus unavailable," every GPU in the Opus cluster was already holding someone else's KV cache. The cluster was physically full.

Sonnet had capacity because more Sonnet hardware exists and it is more efficiently served. The model you chose directly determined which hardware cluster handled your request, and whether that cluster had room.

These tables answer: how much RAM, how many files, how much money, and how much working time?

Assumptions: 0.5 MB GPU VRAM per token (median). Average source file ≈ 1,500 tokens (300 lines × 5 tokens/line). Blended API cost ≈ $5/M tokens (80% input at $3/M + 20% output at $15/M). Active AI coding session ≈ 50,000 tokens/hour (15–20 exchanges/hour at ~3,000 tokens each).

Editorial note: These tables use means and averages, not precise model-specific values. Numbers are round figures intended to convey magnitude, not precision. Actual values vary significantly by model architecture, usage pattern, and Anthropic's infrastructure choices.

Assumption: you use AI heavily all day. Active AI coding = ~50,000 tokens per hour (about 15 exchanges per hour at ~3,000 tokens each — prompt + response). An 8-hour day = ~400,000 tokens consumed.

Editorial note: These tables use means and averages, not precise model-specific values. Numbers are round figures intended to convey magnitude, not precision. Actual values vary significantly by model architecture, usage pattern, and Anthropic's infrastructure choices.

Your single full workday of AI coding (400K tokens) ties up roughly 200 GB of Anthropic's GPU VRAM for the duration of active sessions. Multiply by millions of developers worldwide doing the same thing simultaneously, and the scale becomes clear:

• 1 million active developers × 200 GB each = 200 petabytes of GPU VRAM needed simultaneously
• An H100 GPU has 80 GB of VRAM
• That is roughly 2.5 million H100 GPUs just to serve the KV caches of active sessions
• At ~$30,000 per H100, that is $75 billion in GPUs just for active user sessions
• This is before model weights, training, redundancy, and future capacity

This is why Microsoft announced $80 billion in AI data center investment for 2026 alone. The numbers make sense when you trace a single developer's workday back to server hardware.

Advanced: Building MCP Servers

• Your company has an internal API no public MCP server covers — HR systems, proprietary databases, internal tooling, legacy systems with REST APIs. You build the bridge.
• You want Claude to query your private database — production Postgres, SQL Server, MongoDB. You control the credentials, the queries allowed, and what data is exposed.
• You're building a product on top of Claude Code — your SaaS wants to offer Claude Code integration with your own tools pre-wired.
• You want to wrap an existing CLI tool cleanly — instead of Claude calling the Atlassian CLI via Bash (messy), you build a thin MCP adapter that presents clean structured tools like create_ticket(summary, priority).
• You want Claude to interact with IoT, hardware, or unusual systems — anything you can call from code, you can expose as an MCP tool.

There is no interface file, no IDL, no .h header. The "contract" is the MCP protocol — a set of JSON-RPC 2.0 messages your program must understand. When Claude Code connects to your server:

1. Claude sends initialize — handshake and capability negotiation. Your program responds with what it supports.
2. Claude sends tools/list — "what tools do you expose?" Your program returns a list of tool definitions (name, description, JSON Schema for parameters). Claude caches this for the session.
3. Claude sends tools/call — "call this tool with these arguments." Your program executes the action and returns the result as JSON.

That's the entire protocol for basic tool exposure. Three message types. The rest is your business logic.

The quality of your tool definitions determines how well Claude uses your server. Claude reads the description to understand what the tool does and decides when to call it. The JSON Schema tells it what parameters to provide. Get the description wrong and Claude will misuse or ignore your tool.

{
  "name": "create_ticket",
  "description": "Creates a new Jira issue in the specified project. Use when the user wants to file a bug, create a task, or track work in Jira. Returns the new issue key (e.g. PROJ-1234).",
  "inputSchema": {
    "type": "object",
    "properties": {
      "summary": {
        "type": "string",
        "description": "The issue title — one sentence, specific"
      },
      "priority": {
        "type": "string",
        "enum": ["Low", "Medium", "High", "Critical"],
        "description": "Issue priority"
      },
      "project_key": {
        "type": "string",
        "description": "Jira project key (e.g. PROJ, INFRA). Ask the user if unknown."
      }
    },
    "required": ["summary", "project_key"]
  }
}

Every message is JSON-RPC 2.0 over stdin/stdout. Here is exactly what flows through the pipe:

Claude sends to your program (stdin):

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"claude-code","version":"2.1.75"}}}

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"create_ticket","arguments":{"summary":"Login button broken on Safari","project_key":"PROJ","priority":"High"}}}

Your program responds (stdout):

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"my-jira-server","version":"1.0.0"}}}

{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"create_ticket","description":"Creates a Jira issue. Use when user wants to file a bug or track work.","inputSchema":{"type":"object","properties":{"summary":{"type":"string"},"project_key":{"type":"string"},"priority":{"type":"string","enum":["Low","Medium","High","Critical"]}},"required":["summary","project_key"]}}]}}

{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"Created PROJ-1234: Login button broken on Safari\nhttps://yourjira.atlassian.net/browse/PROJ-1234"}]}}

Each message is one line of JSON terminated by a newline. Your program reads lines from stdin, parses the JSON, acts on the method, and writes a response line to stdout. That is the entire transport layer.

Since this guide is written for Windows developers, here's the simplest possible MCP server in C# using the official ModelContextProtocol NuGet package. This is a real, working implementation:

// 1. Create a new console app: dotnet new console -n MyMcpServer
// 2. Add the package: dotnet add package ModelContextProtocol
// 3. Add to Program.cs:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using ModelContextProtocol.Server;

var builder = Host.CreateApplicationBuilder(args);

// CRITICAL: Log to stderr, NOT stdout — stdout is the protocol channel
builder.Logging.AddFilter("*", LogLevel.Warning);

builder.Services.AddMcpServer()
    .WithStdioServerTransport()   // reads stdin, writes stdout
    .WithToolsFromAssembly();     // discovers tools via [McpServerTool] attribute

await builder.Build().RunAsync();

// MyTools.cs — define your tools here
using ModelContextProtocol.Server;
using System.ComponentModel;

[McpServerToolType]
public static class MyTools
{
    [McpServerTool, Description("Says hello. Use when user wants a greeting.")]
    public static string SayHello(
        [Description("The name to greet")] string name)
    {
        return $"Hello, {name}! This response came from your C# MCP server.";
    }

    [McpServerTool, Description("Adds two numbers. Use for arithmetic.")]
    public static int Add(
        [Description("First number")] int a,
        [Description("Second number")] int b)
    {
        return a + b;
    }
}

// Configure in Claude Code ~/.claude/settings.json:
{
  "mcpServers": {
    "my-csharp-server": {
      "command": "dotnet",
      "args": ["run", "--project", "C:\\MyMcpServer\\MyMcpServer.csproj"]
    }
  }
}

Restart Claude Code, and Claude will discover SayHello and Add as tools it can call. Ask Claude "say hello to Steve" and it will call your C# method directly.

Any program in any language that can read stdin and write stdout is a valid MCP server. You are not limited to npm packages. A compiled Rust binary, a Python script, a Go executable, a PowerShell script — all work. Anthropic provides SDKs for TypeScript and Python that handle the protocol boilerplate, but they're optional.

The minimal Python MCP server is about 30–50 lines:

# Install: pip install mcp
from mcp.server import Server
from mcp.server.stdio import stdio_server
import mcp.types as types

app = Server("my-server")

@app.list_tools()
async def list_tools():
    return [
        types.Tool(
            name="hello",
            description="Says hello to someone",
            inputSchema={
                "type": "object",
                "properties": {"name": {"type": "string"}},
                "required": ["name"]
            }
        )
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "hello":
        return [types.TextContent(type="text", text=f"Hello, {arguments['name']}!")]

async def main():
    async with stdio_server() as (read, write):
        await app.run(read, write, app.create_initialization_options())

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

This is the right question to ask. You can already give Claude access to any CLI program through its Bash tool. So why write an MCP server at all?

Yes, you can absolutely just write a CLI program. If you write my-tool.exe --create-ticket "Bug in login" --project PROJ, Claude can call that from the Bash tool. It works. Claude is smart enough to figure out parameters from a --help output or your instructions. This is the quickest path to "Claude can use my tool."

The concrete reasons to choose MCP over CLI:

• Your tool handles credentials — API keys, database passwords. CLI tools expose these in shell history and process listings. MCP keeps them inside the server process.
• You want reliable parameter passing — Claude occasionally mangles complex CLI flag syntax. JSON Schema parameters are exact.
• You're sharing with a team — a packaged MCP server with a /plugin install or settings.json entry is far easier to distribute than "install this CLI tool and configure these flags."
• The output is structured data — if your tool returns JSON that Claude needs to act on, returning it as a structured MCP response is cleaner than having Claude parse text output.
• You want it to work across multiple AI tools — one MCP server, Claude + Gemini + OpenCode can all use it.

MCP is an open standard. The same MCP server works across multiple AI CLI tools — this is one of its biggest strengths. Write once, use everywhere:

The JSON-RPC protocol is identical across all supporting tools. The only difference is the config file format and location. If you build an MCP server for Claude Code, Gemini CLI can usually use it with only a config change.

• Local script — The most common. Your server is a Python script or Node.js file on your machine. Claude Code launches it with python my_server.py or node my_server.js. No installation required beyond the script being accessible.
• npm package — Package your server as an npm module. Claude Code launches it with npx -y your-package. Users don't need to install anything manually — npx downloads and runs on demand.
• Compiled binary — Rust, Go, or C++ servers compile to a single executable. Fast startup, no runtime dependencies. Point the config at the binary path.
• Remote server (HTTP) — MCP also supports HTTP transport for remote servers. Your server runs in the cloud; Claude connects via HTTPS. Useful for shared team infrastructure — one server, many developers.
• Docker container — Run your server in a container for isolation. Claude Code launches it with a docker run command.

• Official MCP build-a-server guide — Anthropic's documentation with TypeScript and Python examples
• Claude Code plugins repository — Official plugin examples to study
• awesome-claude-code — Community examples of MCP servers and plugins

Making a Plugin: JIRA Integration Example

Claude Code has its own plugin system — separate from MCP servers. A plugin is a package that gives Claude sessions custom slash commands, skills, and hooks. It contains markdown files (skills, commands), JSON configs (manifests, hook definitions), scripts, and optionally compiled programs written in any language — C#, Go, Python, Rust, whatever you want. It gets installed into your local Claude Code environment and runs whenever Claude needs it.

What Languages Can You Use?

This surprises most people: plugins are not language-restricted. The plugin itself is mostly markdown and JSON. The tools it tells Claude to run can be written in anything.

A plugin has four parts, each written in different "languages":

That last row is the key. When a skill tells Claude to run a command, Claude doesn't care what language that command was built in. It just runs it locally and reads the output. So the tools your plugin invokes can be:

• C# / .NET — Build a console app, invoke it as dotnet MyApp.dll --get-ticket PROJ-123 --json or compile to a native .exe
• Go — Compiles to a single static binary with no runtime dependencies. Excellent for cross-platform CLI tools
• Python — python script.py --query "assignee = currentUser()"
• Rust — Single binary, no runtime. Fast and cross-platform
• Node.js / TypeScript — Already available since Claude Code requires Node.js
• Any existing CLI tool — acli, gh, aws, kubectl, curl — if it's on your PATH, your skill can use it

Wait — How Does Claude Even Know What a Plugin Can Do?

This is the question most people skip, and it's the key to understanding the whole system. There's no compiled interface, no API contract, no type system. Instead:

1. At session start, the plugin's SessionStart hook fires and injects a special skill — sometimes called a "meta-skill" — into the conversation context. Despite the fancy name, it's just a regular SKILL.md file whose job is to list every other available skill and when to use each one. Think of it as the table of contents for the plugin. (Note: "meta-skill" is not an official Anthropic term — it's plugin-community jargon. Anthropic's docs just call everything a "skill." The community started calling the auto-injected table-of-contents skill a "meta-skill" to distinguish it, but structurally it's identical to any other skill.)
2. Claude reads that context the same way it reads any system prompt. It now knows: "I have a jira-workflow skill I should invoke when the user mentions a ticket"
3. When Claude invokes a skill, the skill's markdown content gets loaded and Claude follows the instructions — "use acli.exe to query this ticket, check the assignee, transition the status"

The "contract" is natural language. The plugin teaches Claude what tools exist and how to use them, the same way a README teaches a human developer. There is no schema, no function signature, no compiled binding. Just instructions that Claude interprets at runtime.

Where Does the Code Actually Run?

This is the other common misconception. The plugin code does not run in Anthropic's data center. Here's the actual flow:

1. Claude's model runs on Anthropic's GPU servers in a data center — this is where token generation happens
2. Claude Code runs on your local machine — it sends prompts to the API and receives responses
3. When Claude decides to run a command (like acli.exe jira workitem view PROJ-12345), that command executes on your machine, not in the cloud
4. The command's output gets sent back to Claude as context for the next response

JIRA tokens never leave your machine. When the plugin tells Claude to run acli.exe, that command executes locally using credentials stored in your local acli config. The API token goes from your machine directly to Atlassian's servers. Claude's data center never sees it — Claude only sees the JSON output that comes back.

How Plugins Differ from MCP Servers

The Key Insight: Claude Sessions Don't Talk to APIs Directly

This is the most misunderstood part. When an app launches a Claude session to work on a JIRA ticket, Claude doesn't get raw JIRA REST API access. Instead:

1. The host app manages your JIRA credentials securely (API tokens stored via keytar, never exposed to the renderer or to Claude)
2. The host app provides a UI to browse tickets and launches Claude sessions with just a ticket key
3. The plugin handles all JIRA API calls within the session, using its own credential management

The launch looks like this:

// The app passes just the ticket key to Claude, not credentials
const prompt = `/my-plugin:start-work ${ticketKey}`
const args = ['--session-id', sessionId, prompt]

Claude only ever sees the ticket key. The plugin fetches the actual JIRA data using credentials stored separately.

Anatomy of a Plugin

Here's the structure of a production JIRA workflow plugin that integrates ticket lifecycle management into Claude Code:

my-jira-plugin/
├── .claude-plugin/
│   ├── plugin.json          # Plugin metadata & version
│   └── marketplace.json     # Marketplace registration
├── hooks/
│   ├── hooks.json           # SessionStart hook config
│   ├── run-hook.cmd         # Cross-platform polyglot wrapper
│   └── session-start        # Injects skills into every session
├── lib/
│   └── skills-core.js       # Skill discovery & resolution
├── skills/                  # Reusable skills
│   ├── jira-workflow/SKILL.md
│   ├── meta-skill/SKILL.md
│   ├── brainstorming/SKILL.md
│   └── ...
├── commands/                # User-invoked slash commands
│   ├── start-work.md
│   ├── commit.md
│   ├── pr-check.md
│   └── ...
└── agents/                  # Agent templates for subagent dispatch

Step 1: The Plugin Manifest

Every plugin needs a .claude-plugin/plugin.json that declares its identity:

{
  "name": "my-jira-plugin",
  "description": "Development workflow: Jira lifecycle, code review, standards enforcement",
  "version": "1.0.0",
  "author": {
    "name": "Your Team",
    "email": "you@example.com"
  },
  "repository": "https://github.com/your-org/my-jira-plugin",
  "license": "MIT",
  "keywords": ["jira", "tdd", "code-review", "workflows"]
}

And a .claude-plugin/marketplace.json if you want it discoverable by other users:

{
  "name": "my-jira-plugin",
  "description": "Development workflow plugin with Jira integration",
  "owner": {
    "name": "Your Team",
    "email": "you@example.com"
  },
  "plugins": [
    {
      "name": "my-jira-plugin",
      "description": "Jira lifecycle, code review, standards enforcement",
      "version": "1.0.0",
      "source": "./"
    }
  ]
}

Step 2: The SessionStart Hook

Hooks run commands in response to Claude Code events. The hooks.json file tells Claude Code what to execute:

// hooks/hooks.json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "'${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd' session-start",
            "async": false
          }
        ]
      }
    ]
  }
}

The session-start script reads the meta-skill and injects it as context into every new session:

#!/usr/bin/env bash
# hooks/session-start — inject the meta-skill into every session
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"

# Read the meta-skill that tells Claude how to use all other skills
content=$(cat "${PLUGIN_ROOT}/skills/meta-skill/SKILL.md")

# Escape for JSON embedding
escape_for_json() {
    local s="$1"
    s="${s//\\/\\\\}"    # backslashes
    s="${s//\"/\\\"}"    # quotes
    s="${s//$'\n'/\\n}"  # newlines
    printf '%s' "$s"
}

escaped=$(escape_for_json "$content")

# Output JSON that Claude Code picks up as session context
cat <<EOF
{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "${escaped}"
  }
}
EOF

This is the magic — every time Claude starts a session, it automatically knows about all the skills available in the plugin.

Step 3: Slash Commands

Commands are markdown files in commands/ that define user-invocable actions. Here's a start-work command that kicks off JIRA integration:

# commands/start-work.md
---
description: "Start work on a Jira ticket. Looks up the ticket, checks assignment,
  transitions to In Progress, fetches acceptance criteria, and kicks off brainstorming."
disable-model-invocation: true
---

Invoke the jira-workflow skill to start work on the specified ticket.

Follow this sequence exactly:
1. Look up the ticket (fetch summary, status, acceptance criteria, assignee, sprint)
2. Check assignee — if assigned to someone else, STOP and ask
3. Assign to me if unassigned
4. Transition to In Progress
5. Set sprint to active sprint
6. Present the ticket summary and acceptance criteria to the user
7. Then invoke the brainstorming skill to begin design

Notice: the command itself is just instructions. It delegates the actual work to a skill.

Step 4: Skills (Where the JIRA Logic Lives)

Skills are markdown files in skills/*/SKILL.md with YAML frontmatter. The jira-workflow skill contains the actual JIRA integration logic:

# skills/jira-workflow/SKILL.md
---
name: jira-workflow
description: Use when starting work on a Jira ticket, transitioning ticket
  status, updating ticket fields, or checking ticket assignment
---

# Jira Workflow

## Tools

**Primary: acli** (Atlassian CLI) — more token efficient
```bash
# View a ticket with specific fields
acli.exe jira workitem view PROJ-12345 \
  --fields "summary,status,description,assignee" --json

# Transition ticket status
acli.exe jira workitem transition -k PROJ-12345 \
  -s "In Progress" --yes

# Assign ticket to yourself
acli.exe jira workitem assign -k PROJ-12345 -a @me --yes
```

**Fallback: Jira MCP** — when acli fails or for complex field updates
```
getJiraIssue -> editJiraIssue -> transitionJiraIssue
```

The skill teaches Claude how to interact with JIRA — which CLI tool to use, what fields to fetch, what transitions exist, and what to do when things fail. Claude reads this skill at runtime and follows the instructions.

Step 5: Skill Discovery

The plugin includes a lib/skills-core.js module that handles finding and loading skills at runtime:

// lib/skills-core.js — finds SKILL.md files and extracts their metadata
import fs from 'fs';
import path from 'path';

function extractFrontmatter(filePath) {
    const content = fs.readFileSync(filePath, 'utf8');
    const lines = content.split('\n');
    let inFrontmatter = false;
    let name = '', description = '';

    for (const line of lines) {
        if (line.trim() === '---') {
            if (inFrontmatter) break;
            inFrontmatter = true;
            continue;
        }
        if (inFrontmatter) {
            const match = line.match(/^(\w+):\s*(.*)$/);
            if (match) {
                if (match[1] === 'name') name = match[2].trim();
                if (match[1] === 'description') description = match[2].trim();
            }
        }
    }
    return { name, description };
}

function findSkillsInDir(dir, sourceType, maxDepth = 3) {
    const skills = [];
    if (!fs.existsSync(dir)) return skills;

    function recurse(currentDir, depth) {
        if (depth > maxDepth) return;
        for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
            if (entry.isDirectory()) {
                const skillFile = path.join(currentDir, entry.name, 'SKILL.md');
                if (fs.existsSync(skillFile)) {
                    const { name, description } = extractFrontmatter(skillFile);
                    skills.push({ name: name || entry.name, description, sourceType });
                }
                recurse(path.join(currentDir, entry.name), depth + 1);
            }
        }
    }
    recurse(dir, 0);
    return skills;
}

Personal skills in ~/.claude/skills/ shadow plugin skills, so teams can override behavior without forking the plugin.

Step 6: Cross-Platform Hook Wrapper

Since hooks execute commands, Windows compatibility requires a polyglot wrapper — a single file that works as both a Windows batch file and a bash script:

: << 'CMDBLOCK'
@echo off
REM Windows batch portion — finds bash and delegates
if "%~1"=="" ( echo run-hook.cmd: missing script name >&2 & exit /b 1 )
set "HOOK_DIR=%~dp0"

REM Try Git for Windows bash
if exist "C:\Program Files\Git\bin\bash.exe" (
    "C:\Program Files\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5
    exit /b %ERRORLEVEL%
)
REM Try bash on PATH
where bash >nul 2>nul
if %ERRORLEVEL% equ 0 ( bash "%HOOK_DIR%%~1" %2 %3 %4 %5 & exit /b %ERRORLEVEL% )
exit /b 0
CMDBLOCK

# Unix portion — run the named script directly
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
exec bash "${SCRIPT_DIR}/$1" "${@:2}"

The trick: Windows cmd.exe sees the : as a label and runs the batch code. Bash sees : as a no-op and skips to the bottom.

The Full Flow

Here's what happens end-to-end when a developer types /start-work PROJ-12345:

1. SessionStart hook already fired — Claude knows about all available skills
2. Slash command start-work.md tells Claude to invoke the jira-workflow skill
3. Skill jira-workflow instructs Claude to:
   • Run acli.exe jira workitem view PROJ-12345 --fields "summary,status,description,assignee" --json
   • Check assignee — stop if assigned to someone else
   • Transition: acli.exe jira workitem transition -k PROJ-12345 -s "In Progress" --yes
   • Set sprint: acli.exe jira workitem edit -k PROJ-12345 --custom "customfield_10007:42" --yes
4. Claude presents the ticket summary and acceptance criteria to the developer
5. Next skill (brainstorming) kicks in automatically to design the approach

Credentials never touch Claude's servers. The plugin instructs Claude to run local CLI commands that use locally-stored API tokens.

Installation & Distribution

Users install a plugin with two commands:

# Register the marketplace (one time)
/plugin marketplace add your-org/my-jira-plugin

# Install the plugin
/plugin install my-jira-plugin@my-jira-plugin

The plugin gets downloaded to ~/.claude/plugins/cache/my-jira-plugin/. A host app can manage updates programmatically:

// A host app can keep the plugin updated automatically
await runCommand(['plugin', 'marketplace', 'update', 'my-jira-plugin'])
await runCommand(['plugin', 'update', 'my-jira-plugin@my-jira-plugin'])

Building Your Own JIRA Plugin

To build a plugin that integrates with JIRA (or any external API), follow this pattern:

1. Create the manifest — .claude-plugin/plugin.json with name, version, description
2. Add a SessionStart hook — inject context so Claude knows about your skills on every session
3. Write skills as markdown — teach Claude which CLI tools to use and how (e.g., acli for JIRA, gh for GitHub)
4. Create slash commands — entry points that chain skills together into workflows
5. Handle credentials locally — use tools like acli with saved configs or keytar; never pass tokens through Claude
6. Publish to the marketplace — add .claude-plugin/marketplace.json so others can install it

The key design principle: skills are instructions, not code. You're teaching Claude a workflow in natural language, backed by CLI tools that handle the actual API calls. Claude never needs raw REST access — it executes local commands that have their own authentication.

A Plugin Is Not a Hook

This is easy to confuse. A plugin is not a hook. A plugin contains hooks, along with skills, commands, and agents. These are four distinct components that live inside a plugin:

When we say "the SessionStart hook fires," we mean: one specific component inside the plugin (the hook) executes a command in response to a Claude Code event. The plugin as a whole is the package that contains that hook, plus all the skills, commands, and agents.

Is a Plugin "Live" or Dormant?

Dormant. Between sessions, the plugin is just files sitting on your local disk at ~/.claude/plugins/cache/. No process is running. Anthropic's servers have zero awareness that your plugin exists. Nothing is consuming memory, CPU, or tokens.

But it wakes up automatically when you start a session. Here's the lifecycle:

1. You start a Claude Code session — the plugin is dormant files on disk
2. Claude Code fires the SessionStart event — the plugin's hook runs a script
3. The hook injects the meta-skill — a markdown document listing all available skills gets added to the conversation context
4. From this point on, Claude "knows" what the plugin can do — because the meta-skill is part of its context window
5. When you close the session — the plugin goes back to dormant. Nothing persists in memory.

So the plugin is dormant between sessions, active within sessions, and the transition happens automatically via the SessionStart hook.

Can Claude Use the Plugin Without Being Asked?

Yes — and this surprises most people. Claude can invoke plugin skills on its own, without the user explicitly asking, if the meta-skill instructs it to. Here's a concrete example of how aggressive this can be. A real production meta-skill contains instructions like:

With instructions like this in the context, if you say "fix the bug in ticket PROJ-12345," Claude will:

1. Read its injected context and see it has a jira-workflow skill
2. Invoke that skill autonomously — without asking you first
3. Follow the skill's instructions to run acli.exe locally to fetch the ticket

However, slash commands can opt out of this. The disable-model-invocation: true frontmatter flag means only a human can type that command. So /start-work requires you to type it, but the underlying jira-workflow skill that it delegates to can be invoked by Claude freely.

Human-Only vs. Claude-Autonomous: The disable-model-invocation Flag

This is one of the most important design decisions a plugin author makes. Every slash command in a plugin has a choice: can Claude invoke it on its own, or does only a human get to type it?

The disable-model-invocation: true flag in a command's YAML frontmatter means: this command requires a human to type it. Claude cannot decide on its own to run /start-work PROJ-12345. Only you can. But here's the subtlety — that restriction only applies to the command, not the skill it delegates to. The jira-workflow skill that /start-work invokes? Claude can call that skill directly, any time, without asking.

This creates a two-tier permission system:

Think of it like this: the command is the front door with a lock — only the homeowner (you) has the key. The skill is the toolbox inside the house — once someone is inside (via a command you approved, or via Claude's autonomous judgment based on the meta-skill instructions), they can use any tool freely. This lets plugin authors put guardrails on initiating workflows while still letting Claude work autonomously within them.

Plugins and Token Cost

This is the part nobody talks about. The plugin's "contract" IS token usage. There is no free metadata channel, no side-band, no compiled shortcut. Everything Claude knows about the plugin travels as tokens in the conversation context.

Here's what that means concretely:

The meta-skill is the expensive part because it's always there. Every prompt you send — even "what does this variable mean?" — carries the full meta-skill as context overhead. A plugin with 19 skills needs a bigger meta-skill "menu," which means more baseline token cost on every message.

The full flow, in terms of what consumes tokens:

1. Session starts → hook fires → meta-skill (~2K tokens) injected into context
2. Every prompt you send now carries that meta-skill as context overhead
3. Claude reads it, sees available skills, decides which to invoke
4. When Claude invokes a skill, that skill's full content loads — more tokens added to context
5. Claude follows the skill instructions, runs local commands, gets output
6. Command output (JIRA JSON, git diff, etc.) comes back as yet more context tokens

This is a real design tradeoff: more plugin capabilities = more tokens per message = more cost. A lean plugin with 3 skills has minimal overhead. A comprehensive plugin with 19 skills pays a significant per-message tax just for Claude to know what's available. Plugin authors should think carefully about what goes in the meta-skill versus what gets loaded on demand.

Confusing Terms

This guide has uncovered a surprising amount of confused terminology, misleading names, and inconsistent definitions in the world of AI coding tools. Some of this is Anthropic's fault. Some is the broader AI industry's fault. Some is just the natural fog that forms when technical people name things for themselves and forget that others have to understand them too.

Here is a complete accounting of everything we found.

Count: 27 documented confusions. Attribution: ~13 to Anthropic (purple rows), ~7 to the broader AI/software industry, ~4 to evolving product definitions. This list will grow — the AI tooling space moves faster than its documentation.

Find Your Path

Not sure where to start? Pick whoever sounds most like you.

Your First 15 Minute Session with Claude Code

Theory later. Start here. Do these steps in order in a real project directory and you'll understand more in 15 minutes than you will from reading the whole Manifesto first.

cd C:\repos\MyProject

claude

Give me a high-level overview of this codebase. What does it do, how is it structured, and what are the main entry points?

Where is the user authentication handled? Show me the relevant files and the flow.

Find any TODO comments in the codebase and list them with file paths and line numbers.

Run the tests and tell me if anything is failing.

What would a good test suite look like for this project? What's the most important thing to test first?

I want to [add feature X / refactor Y / fix bug Z]. Before you start, describe your approach: which files you'll change, in what order, and what risks to watch for.

An AI Practitioner's Guide

This is practical advice for building real software with AI coding tools. Not theory. Not hype. This is what works when you're 30,000 lines deep and still adding features.

if (platform == "claude") { doX() }
else if (platform == "gemini") { doY() }
else if (platform == "codex") { doZ() }

registry = {
  claude: { handler: doX, color: "blue" },
  gemini: { handler: doY, color: "yellow" },
  codex:  { handler: doZ, color: "magenta" }
}
// Then: registry[platform].handler()

Remote Control from Your Phone

Shipped February 25, 2026. Start a task on your laptop, put it in your bag, and keep full control from your phone. The session runs locally on your machine — your filesystem, MCP servers, tools, and project config all stay available. You just control it remotely.

Requirements

• Claude Code v2.1.52+ — update with npm update -g @anthropic-ai/claude-code
• Any paid Claude plan — Remote Control is available on all plans. Team and Enterprise admins may need to enable Claude Code in admin settings first.
• Authenticated CLI — run /login if you haven't already
• The Claude mobile app (iOS/Android) or any browser pointed at claude.ai/code

Method 1: From an Existing Session (/rc)

You're already in a Claude Code session and want to hand it off to your phone:

1. Optional but recommended: type /rename MyTask so you can find the session by name on your phone
2. Type /rc (short for /remote-control)
3. A session URL appears in your terminal
4. Press spacebar to toggle a QR code display
5. Scan the QR code with your phone — it opens directly in the Claude app or browser
6. You're now controlling the session from your phone. The conversation stays in sync.

Method 2: Start a New Remote Session

Start a session that's remote-ready from the beginning:

1. cd to your project directory
2. Run claude remote-control
3. The terminal shows a session URL and QR code (spacebar to toggle)
4. Scan or open the URL on your phone
5. Start prompting from your phone immediately

Three Ways to Connect from Your Phone

Remote Control sessions show a computer icon with a green dot in the session list when online.

Enable for Every Session (Auto Mode)

If you always want Remote Control available:

1. Type /config inside any Claude Code session
2. Set "Enable Remote Control for all sessions" to true
3. Every future session will automatically be available for remote connection

What Happens Under the Hood

• Claude Code registers with the Anthropic API and polls for work
• When you connect from your phone, the server routes messages between your device and your local session over a streaming connection
• All traffic travels through the Anthropic API over TLS (encrypted)
• Your code never leaves your machine — only conversation messages are transmitted
• One remote connection per session (you can't have two phones controlling the same session)

Constraints and Gotchas

• Terminal must stay open. If you close the terminal or stop the process, the session ends. Minimize it, don't close it.
• Laptop sleep is okay. The session reconnects automatically when your machine wakes up.
• 10-minute network timeout. If your machine loses network for more than ~10 minutes while awake, the session times out and the process exits.
• All paid plans. Remote Control is available on all Claude plans. Team and Enterprise admins may need to enable Claude Code in admin settings.
• Phone typing is painful. Remote Control is best for monitoring progress, approving tool uses, and giving short follow-up prompts — not for writing detailed instructions. Start the big prompt on your laptop, then monitor from your phone.

Practical Workflow

1. At your desk: start a Claude Code session, give it a complex task
2. Type /rc, scan the QR code with your phone
3. Close your laptop lid (sleep is fine)
4. From your phone: watch Claude work, approve tool uses, answer questions
5. Back at your desk: open your laptop, the terminal is still running, continue in the terminal

Other AI Coding CLIs

Claude Code isn't the only AI coding CLI. Here's how the major players compare on the features discussed in this guide. All of these are terminal-based coding assistants — not IDE plugins, not chat UIs.

1. Claude Code (Anthropic) is the subject of this entire guide. It has the deepest architecture of any CLI coding tool — skills, hooks, slash commands, agents, memory, plan mode, and Remote Control. If you invest time in learning one CLI deeply, this is the one.

2. Codex CLI (OpenAI) is OpenAI's answer to Claude Code. It uses the GPT-5 Codex model variants, stores sessions in SQLite, and supports forking. It runs in a sandbox mode with tiered approval for commands. Its main advantage is the GPT-5 Codex model family, which has strengths in certain code generation tasks. Weaker extension architecture than Claude Code.

   Codex uses AGENT.md the same way Claude uses CLAUDE.md. Same concept: a markdown file loaded at session start that gives the AI persistent instructions. If you have a well-crafted CLAUDE.md, copy it to AGENT.md and Codex will pick it up. Your architecture rules, coding standards, and anti-patterns carry over with zero extra work.

   Windows users: Codex creates sandboxed Windows user accounts on your machine as part of its security model. You may notice new user accounts (named something like "Codex Sandbox" or similar) appearing in your Windows user list after installing Codex. This is intentional — those restricted accounts run Codex's operations with limited OS permissions so that commands cannot reach beyond what a low-privilege user can do. Do not delete them; removing them breaks Codex's sandboxing. This is specific to Codex's Windows implementation and is not something Claude Code does.

3. Copilot CLI (GitHub / Microsoft) is backed by Microsoft's investment in GitHub and OpenAI. It offers multiple model choices (Claude Haiku, GPT-4.1, GPT-5 Mini), which is unusual — most CLIs are locked to their vendor's model. It has session persistence and file editing but no forking, no skills, no hooks. Strong choice if your organization is already deep in the GitHub ecosystem.

4. OpenCode is open-source and model-agnostic — you can point it at Claude, GPT, or any other supported provider. This makes it attractive for organizations that want control over which AI model processes their code, or that need to run everything on-premises. The trade-off is a thinner feature set: no skills, no hooks, no memory. A good choice for teams with strict data residency requirements.

5. Gemini CLI (Google) brings Google's Gemini models to the command line. Gemini 2.5 Pro has an exceptionally large context window, which helps with large codebases. It supports MCP servers and has session persistence. Weaker extension architecture than Claude Code, but the model itself handles large-scale codebase analysis well. Natural choice if your organization is on Google Cloud.

All five CLIs above send your code to a cloud API. Ollama, LM Studio, Jan, and similar tools take a different approach: they run AI models locally on your machine, with no data leaving your network. This is a fundamentally different architecture.

Ollama is the most popular. It downloads open-source models (Llama, Mistral, CodeLlama, DeepSeek, and others) and runs them locally via a REST API on localhost:11434. Other tools (including OpenCode) can point at an Ollama endpoint instead of a cloud API, giving you local inference with a familiar CLI experience.

The trade-offs are real:

• Privacy: Your code never leaves your machine. For proprietary or classified code, this is critical.
• No subscription cost: After hardware, inference is free.
• Hardware requirements: Running a capable coding model requires a modern GPU with significant VRAM (16GB+). Weak hardware means slow, low-quality results.
• Model quality gap: Local open-source models are improving fast but are still behind GPT-5 and Claude Opus for complex reasoning and code generation as of 2026.
• No built-in tools: Ollama is an inference server, not a coding assistant. You need a separate CLI layer (like OpenCode pointed at Ollama) to get file editing, tool use, and session management.

If your organization has strict data policies that prohibit sending code to any external service, the Ollama + OpenCode combination is worth investigating. For most developers without those constraints, cloud-based CLIs currently offer better model quality and richer tooling.

The AI coding tool space is moving fast. This guide covers the five most widely used cloud-based CLIs as of early 2026, but the following tools also exist and may be relevant depending on your stack:

1. Aider — An open-source Python-based coding assistant with strong git integration. Predates Claude Code and has a loyal following. Works with multiple models.
2. Continue — Primarily a VS Code/JetBrains extension but has CLI capabilities. Model-agnostic.
3. Cline — VS Code extension with CLI roots. MCP support, model-agnostic.
4. Cursor — An IDE (fork of VS Code) with deeply integrated AI. Not technically a CLI but competes for the same workflow.
5. Amazon Q Developer CLI — AWS's coding assistant. Strong if you live in the AWS ecosystem.
6. Mistral Le Chat — European-based, GDPR-native AI. CLI tooling is early-stage but growing.

This is not an exhaustive list. New tools appear monthly. The architectural concepts in this guide (sessions, hooks, MCP, memory, skills) are Claude Code-specific, but the underlying ideas — persistent context, tool use, cross-session memory — are becoming table stakes across the industry.

The honest answer depends on your situation, not on which tool is theoretically best:

This trips people up constantly. Claude Code is the CLI application. The Claude models (Opus, Sonnet, Haiku) are the AI brains that run inside it. They are separate. You can switch models mid-session with /model without restarting anything.

Think of it this way: Claude Code is like Visual Studio. The Claude model is like the C# compiler version. You can change the compiler version without reinstalling Visual Studio.

The same separation applies to other CLIs: Copilot CLI lets you choose between Claude Haiku, GPT-4.1, and GPT-5 Mini. OpenCode can point at any model via Ollama or an API. The CLI is the tool; the model is the engine. You can swap engines.

Editorial teaching model — not benchmark scores. IQ numbers are estimated shorthand for relative reasoning quality (Opus 4.6 = 100 baseline), not official measurements. Awareness numbers are calculated from published token limits and are factual.  ■ IQ = editorial estimate  ■ Awareness = official fact

People talk about AI quality as if it's one thing. It isn't. There are two independent dimensions:

• IQ — The model's reasoning capability. How well it thinks, writes code, solves problems. Opus > Sonnet > Haiku. GPT-5 vs GPT-4.1. This is what most people compare.
• Awareness — How much information the AI can hold in mind at once. If IQ is how smart it is, Awareness is how much of the room it can see. A genius who can only read one page at a time is limited. A less brilliant person who can read the whole book at once may outperform them.

Think of it like image fidelity. A single photograph can be ultra-high-resolution — every pixel tiny. That's high IQ. A movie covers far more ground with thousands of frames, but each individual frame may be lower resolution than a still. That's high Awareness. A brilliant photograph of one page of your codebase is less useful than a full movie of the entire project, even if each movie frame is slightly softer.

We measure Awareness in pages — one standard 8.5×11 page of dense text ≈ 500 words ≈ 750 tokens. This gives you an intuitive sense of how much the AI can "see" at once. More Awareness is most valuable on large codebases, long sessions, and cross-file reasoning. For small, narrow tasks — renaming a variable, explaining a single function — extra Awareness may matter less than reasoning quality (IQ).

GitHub Copilot CLI offers Claude Haiku 4.5 as one of its model choices. So if both Claude Code and Copilot can run Claude Haiku — are they the same tool?

No. Same brain, completely different truck.

When Copilot routes to Claude Haiku, you get Haiku's reasoning ability. That part is identical. But Copilot does not give Claude:

• CLAUDE.md — persistent project instructions loaded every session
• Skills — specialized instruction documents loaded on demand
• Hooks — automated commands triggered by events
• Memory — notes that persist across sessions
• Agents/Worktrees — delegating subtasks to isolated environments
• Plan Mode — design-before-coding workflow
• The full context window Claude Code provides to the model

The model is the IQ. The platform wrapped around it determines the Awareness and the workflow. A brilliant person handed a blank notepad is less effective than a capable person with a full desk, reference library, filing cabinet, and an organized team of assistants.

Why Copilot offers Claude Haiku at all: Anthropic licenses the Claude models via API. Microsoft/GitHub pays to route calls through Anthropic's API and bundle it into Copilot. Same model, different packaging, different surrounding toolset, different pricing, different context limits. The model is a commodity; the tooling around it is where the differentiation happens.

Claude Code has the richest extension architecture by far — skills, hooks, slash commands, MCP servers, agents, memory, and plan mode are all unique to it. The other CLIs are primarily prompt-and-respond tools with session persistence. If you're investing time learning AI coding tool architecture, Claude Code is where that investment pays off the most.

That said, all five CLIs can edit files, run commands, and resume sessions. For basic coding tasks, the experience is similar across all of them. The differences emerge when you want automation (hooks), extensibility (MCP), reusable workflows (skills/commands), and cross-session knowledge (memory).

Glossary

Every tool, acronym, and term used in this guide — defined in one place. Anthropic’s confusing naming is called out inline where it applies.

Code Commenting Practices to Reduce Drift

Comments lie. Not intentionally — they were true when written. But refactors move functions, responsibilities shift, and the comments stay behind describing a structure that no longer exists. The result is code drift: the gap between what comments say the code does and what the code actually does.

AI makes this worse before it makes it better. AI reads comments as instructions. If a file header says "Contains: session launch, fork handling, profile creation" but the refactor moved two of those elsewhere, AI will confidently generate code in the wrong place — because the comment said so.

Why Drift Happens

The drift in a real production project happened for predictable reasons:

• Top-of-file comments were too detailed — full function inventories that became stale the moment any function moved
• Refactors moved functions without updating headers — the fix was done but the documentation wasn't
• File headers were used as mini changelogs — describing history instead of current responsibility
• No rule for what a file header should contain — so every developer used their own format
• Function-level and file-level docs overlapped badly — the same information was in two places, and they fell out of sync

The Fix: Contract-Oriented File Headers

Replace function inventories with stable contract-style headers. The right format for any file is:

• File — the file name
• Namespace — which architectural boundary it belongs to
• Purpose — what this file owns (not what functions it contains)
• Notes (optional) — critical invariants that anyone touching this file must know

This format is searchable, durable, and meaningful to both humans and AI. It survives refactors because it describes ownership, not contents. Contents change. Ownership changes far less often.

Example: Before and After

Before (inventory style — drifts immediately):

# src/session/launch.ps1
# Contains: New-Session, Fork-Session, Continue-Session, Resolve-Background,
#           Get-GitBranch, Prompt-GitIdentity, Create-WTProfile, Write-PendingMapping

After (contract style — stays true):

# File:      src/session/launch.ps1
# Namespace: session
# Purpose:   Session lifecycle entry points — new, fork, and continue paths.
#            All paths call shared helpers in session/lifecycle.ps1 for artifact
#            creation. No platform logic here — read from PlatformRegistry.
# Notes:     INVARIANT: Every path that creates a WT profile must clean it up
#            in the catch block. Track with $profileCreated flag.

The second version will still be accurate after you move three functions out of the file. The first won't.

Function-Level Comments

Detailed behavior belongs on functions, not file headers. Use your language's native documentation block:

# PowerShell example
function New-Session {
    <#
    .SYNOPSIS
        Starts a new Claude Code session in Windows Terminal.
    .PARAMETER Platform
        Platform key from PlatformRegistry (e.g. 'claude', 'codex').
    .NOTES
        Creates a WT profile and pending mapping. Both are cleaned up
        on failure in the catch block — see $profileCreated flag pattern.
    #>

This way: the file header describes the boundary. The function comment describes the contract. Neither tries to do the other's job.

Rules to Add to CLAUDE.md

Add these to your CLAUDE.md to prevent drift from the start. AI will enforce them with every subsequent code generation:

## Comment Standards

File headers must contain: File, Namespace, Purpose, and optional Notes.
File headers describe ownership and invariants — not a list of every function.
Function inventories in file headers are forbidden unless the file is under 50 lines and stable.

When a refactor changes a file's responsibility, update the file header in the same commit.
When you split a file, both new files get fresh headers that reflect their new, narrower ownership.

Use function .SYNOPSIS blocks (or language-equivalent) for detailed behavior documentation.
File headers describe boundaries. Function blocks describe contracts.

Comments must describe current truth, not historical intent.
If a comment describes something that was true in v3 but isn't in v7, delete it.
History belongs in git log and CHANGELOG.md — not in source code.

The Short Version

• Keep file headers short and stable — ownership and invariants, not inventories
• Put detailed behavior on functions, not files
• Treat header updates as part of any refactor, not optional cleanup
• Reject comments that describe history instead of current responsibility
• Encode the rules in CLAUDE.md so AI enforces them automatically

Case Studies

Real projects, real mistakes, real lessons. Each case study documents what actually happened when AI coding tools were used in production — what worked, what collapsed, and what was learned.

Engineering with AI: From Concept to Product

Building from the ground up with AI in mind — and documenting every step of the way

The Idea

I want to use the occasion of a new product as a case study for doing AI-engineering — as opposed to AI-coding (documenting my steps along the way). The product: a tool that lets you draw your UI on a drawing tablet — screens, block diagrams, workflow sketches — and then feed those drawings directly into an AI so it can generate screen layout designs. The specific use case was for adding screens to an existing product, but would be nice to draw screens for a new product from scratch with hand-drawn designs as the AI's input.

The insight that makes this worth a case study is not the product itself. It is the discipline of how it was started. Everything in this story was meant to be done before a single line of code was written (excepting any POC work for proving the technological capabilities).

Pitfall Avoided: Turning Concept Into Product Too Fast

AI could already have a working product built by the time you finish writing this document. That is the trap. You double the time to the first exciting demo, and that takes willpower to accept. But it pays off in every subsequent week.

Vibe coding is a strong pull. It is a dopamine hit. It makes you want to have something running tonight. The pattern in Case Study 1 is exactly this — a Saturday morning of pure velocity that built up a debt that took many change-sets to pay down.

AI Virtue #1: Patience

Patience is not waiting. It is choosing a slower path now to walk a faster path later. The steps below are all "slow" in the sense that none of them produce a running product. They all produce something more durable: a shared understanding between you and the AI of exactly what you are building and why.

The Process, Step by Step

1. GitHub Repo — Early

Don't talk about it. Do it. Before architecture docs, before POC, before any serious thinking — create the repo. Every decision made after this point is recorded somewhere. This is not optional.

2. Narrate the Idea in a Document

Write down what the product is. Not code — prose. Describe it the way you would describe it to a colleague over lunch. In this case: "I want to draw screens on my drawing tablet, photograph or export them, and feed those drawings into Claude so it can produce screen layout designs I can start coding from." That is the idea. Write it down before anything else.

This step is the design process. The act of writing forces you to make decisions you would otherwise defer. Vague ideas become concrete questions. Concrete questions reveal scope. Scope reveals what you actually need to build.

3. POC — Small Vibe Coding to Prove the Idea Works

At this stage, and only at this stage, vibe coding is appropriate. Write the smallest possible amount of code to answer one question: does this actually work? In this case: can Claude receive a tablet drawing and produce a useful screen layout? If yes, proceed. If no, pivot now before you have written a design document for a product that does not work.

The POC is not production code. It is a disposable experiment. Treat it that way.

4. Draw Your Screens and Block Diagrams

Before writing a single technical requirement, draw every screen. This discipline comes from a long-standing principle: designing from the screens drives every other decision. If the screen design is iterative, you will discover interfaces. You will find data that needs to move between screens. You will find menus and flows you did not know you needed.

Draw on paper if you have to. Then photograph or export and feed them into the AI. You are not just documenting — you are doing design work in the medium that AI can consume.

5. Write the Full Technical Design Document

This step is critical. Document every layer of the system:

• How many types of menus exist? What is in each one? Can they share a generic menu system?
• How many screens are there? What data does each screen take as input and produce as output?
• What is the physical path from tablet drawing to AI consumption? Every hop documented.

Writing this document is not overhead. It is architecture. Everything that would otherwise be decided ad-hoc during coding is decided here, where decisions are cheap and reversible.

6. Multiple AIs Consume the Design and Compete on Architecture

Feed the design document to more than one AI and ask each for an architecture plan. Then have them go back and forth until you reach a consensus. This is competitive planning: two AIs producing proposals, critiquing each other's work, and converging on something better than either would have produced alone.

A practical note: ask each AI which of the two is better suited to implement a given component, and which is better suited to review it. They will give you honest answers, and those answers are useful.

6b. Extract and Approve Constraints Before Code

Before the AI touches a single line of code, there is a critical gate: constraint extraction and approval.

Have the AI write a .constraint-extraction.md file that extracts every architectural constraint, decision, boundary, and assumption from the final plan. This file is not code. It is the explicit statement of "what must be true for this code to be correct."

You review this file. You look for gaps, missing cases, forgotten boundaries. You ask questions. You push back if constraints are unclear. Only when this file is complete and correct do you approve it explicitly.

Only after approval does code begin. If code appears without approved constraint extraction, the commit is rejected and pointed back to the constraint file. This is not optional.

Why does this matter? Architectural work fails when constraints are implicit. They get embedded in code, discovered in review, and require rework. Making them explicit first prevents the entire class of architectural rework. Constraints extracted and approved before code almost never surface as bugs later.

7. Bootstrap from Your Prior Work

Have the AI consume your CLAUDE.md and AGENTS.md from previous projects, and update them to become this project's founding documents. This is a critical step. It takes your engineering discoveries from prior work — every rule that came from something that actually broke — and puts this project on a good footing before a line of code is written.

You are not starting from scratch. You are transferring institutional knowledge.

8. AI Designs the Directory Structure

Before any code moves anywhere, have the AI propose a directory structure for both docs and code. Then have a second AI critique it. Directory structure is not a detail — it determines how the project grows. A poor structure that gets committed early becomes a migration cost later.

9. Design for Scale: Local vs. Cloud

Have the AI model both paths: a local-server architecture and a cloud-hosted architecture. This is not about picking one today. It is about making sure the design is not accidentally incompatible with the path you will want later. Decisions made here are cheap. The same decisions made at v5 cost retrofits.

10. Move POC Code Into the Proper Structure

Now, and only now, the POC code moves from its throwaway location into the real directory structure. The AI does the move. The move is mechanical — the structure was designed in step 8. Nothing is rewritten yet. The goal is to have working code in the right place before any new features are added.

11. Testing Plan, Tests, and a Test Launcher — Before Features

Have both AIs come to a testing plan together. Then have them write the tests. Then have them write a test launcher so that tests run automatically with every change.

Insist on red-green testing from this point forward. Every step of the way. Every new feature must come with new tests. This is not optional. Case Study 1 documents what it costs when test infrastructure is added after the fact. Do not repeat that.

12. Implement One Small Feature, Test, Check In

Now you are ready to build. Take the smallest complete feature from the master plan. Implement it. Run the tests. Check in. Repeat.

The velocity from here feels slower than pure vibe coding. But it compounds. Features land without breaking previous features. The AI has a shared understanding of the architecture. Additions fit because the structure was designed to accept them.

Execute each feature using RUN_PLAN.md as your constraint. Write a feature-specific plan (e.g., add-user-authentication.md), then hand it to the AI with this command:

Execute add-user-authentication.md using RUN_PLAN.md as your
rule and constraint. Complete Phase 0 preflight first, then
implement one bounded change at a time. Run tests after each change.

After each feature lands, do a hostile code review to catch local bugs, and a tough review using PR_TOUGH.md to catch architectural drift:

Do a hostile review of add-user-authentication work, then a
tough architectural review using PR_TOUGH.md. Output both to
PR_AUTH_FINDINGS.md. Block merge if CRITICAL.

What This Avoids

Case Study 1 is the counter-example. Every step above corresponds to something that was skipped there and had to be paid for in v9:

The One-Sentence Version

Do all the design work first, let the AI do it with you, and then build — because the AI will build exactly what you designed, and if you did not design it, the AI will invent it.

Code Review Methodology: The Hostile Review

Once your product is being built, features are landing, and tests are passing — how do you know the code is actually correct? Passing tests and successful builds are evidence, not proof. This is where a rigorous, AI-driven code review process becomes essential.

The methodology below is called a hostile code review. The word "hostile" is deliberate. You are not asking the AI to summarize what the code does. You are telling it to assume there are bugs and hunt for them. This is the difference between a review that confirms your expectations and a review that challenges them.

The Structure of a Hostile Review Prompt

A hostile review prompt has five parts, each serving a distinct purpose. Skip any one of them and the AI will fill the gap with generic advice instead of real findings.

1. Mindset. Tell the AI to assume there are bugs. Tell it not to waste time on style, naming, or refactoring unless they hide a real defect. Tell it to be skeptical of passing tests. This sets the tone for the entire review.

2. Scope. Define exactly which slice of the codebase to review. Name the feature, the files, and the boundaries. If you do not scope the review, the AI will wander into unrelated code and dilute its findings with irrelevant observations.

3. Known Incompletes. Tell the AI what is deliberately unfinished. Without this, half the findings will be "this feature is not complete" — which you already know. The rule is: do NOT report these as bugs unless the current code incorrectly pretends they are complete.

4. Trace Paths. Tell the AI exactly what to trace. A code review that reads files in isolation misses wiring bugs. The AI must follow the full path: UI event → handler → HTTP request → controller → service → data layer → response. Every hop. Every assumption.

5. Output Format. Require structured output: findings ordered by severity, each with a file/line reference, a description of the actual failure mode, and an explicit confidence level. Require a separate section for residual risks and test gaps. If there are no findings, require the AI to say exactly "No findings" — no padding, no summaries of what the code does.

Sample Prompt: Hostile Code Review

Below is a real prompt used to review a feature slice in a production codebase. It follows all five parts of the structure above. You can adapt this template to any feature in any codebase.

You are doing a hostile code review of the current [feature] slice.

Mindset:
- Assume there are bugs.
- Hunt for correctness issues, regressions, bad assumptions,
  broken wiring, hidden runtime failures, invalid semantics,
  missing guards, and missing tests.
- Be skeptical of passing tests and successful builds.
  They are evidence, not proof.
- Do not waste time on style, naming, or refactoring
  unless they hide a real defect.
- Do not review unrelated repo churn. Stay on the [feature]
  slice only.

Scope:
Review only the current [feature] work:
- [component 1]
- [component 2]
- [component 3]
- tests added for this slice

Known incomplete by design (do NOT report as bugs unless
the current code incorrectly pretends they are complete):
- [known incomplete item 1]
- [known incomplete item 2]
- [known incomplete item 3]

Files to inspect at minimum:
- [path/to/file1]
- [path/to/file2]
- [path/to/file3]

Context files to compare against:
- [path/to/spec_or_design_doc]
- [path/to/sample_data]

You must manually trace the full path:
1. UI event -> handler -> HTTP request shape
2. Controller action -> service call -> response
3. Service method -> data builder -> output shape
4. Data source -> field mapping -> fallback behavior
5. Tests -> what is covered vs. what is not

You must actively look for:
- endpoint/route mismatches
- wrong HTTP verb or response type assumptions
- null-path runtime exceptions
- invalid output shape relative to spec/samples
- unsafe assumptions about data always existing
- UI errors when server returns error responses
- cases where malformed input slips through
- missing tests for real failure paths

Run these commands:
- [test command for this slice]
- [build command]

If useful, inspect relevant diffs and current file contents,
but do not modify code.

Output format:
1. Findings
- Findings first, ordered by severity.
- Each finding must include:
  - severity: Critical / High / Medium / Low
  - a one-line title
  - exact file and line reference
  - why it is a real bug/risk now
  - the concrete failure mode or reproduction path
- If you are unsure, say so explicitly and explain
  what evidence would confirm it.

2. Residual Risks
- Only risks that are real and current.
- Separate these from confirmed findings.

3. Test Gaps
- Only high-value missing tests for this slice.

Rules:
- If there are no findings, say exactly "No findings."
- Do not pad the answer with summaries of what the code does.
- Do not recommend future roadmap work unless it exposes
  a current defect.
- Do not confuse "unfinished by design" with "broken now."
- Be strict.

Why This Works

This prompt structure works because it eliminates the three failure modes of AI code review:

• Vague scope — "review my code" produces a book report. Named files and traced paths produce findings.
• False positives from known incompletes — without the "known incomplete" section, half the findings are things you already know. This wastes your time and trains you to ignore the review.
• Unstructured output — a wall of prose buries the critical finding on page 3. Severity-ordered, file-referenced findings let you act immediately.

Architectural Code Review with PR_TOUGH.md

The hostile review above catches bugs in individual features. But code can be locally correct and architecturally wrong: canonical truth split across files, boundaries violated, caches treated as authoritative, old patterns preserved under new names.

PR_TOUGH.md is a framework for catching that class of drift. It defines nine categories of architectural violation specific to your documented architecture, and structures reviews to hunt for them systematically. Copy PR_TOUGH.md from the root of this repository into your project, customize the nine categories to match your architecture, and use it to review changes that touch core boundaries.

When to Use PR_TOUGH.md

Use PR_TOUGH.md instead of (or in addition to) hostile review when:

• Your commit touches core architectural seams — data storage, canonical authority, namespace boundaries
• Your commit modifies tests, build manifests, or docs claiming that architectural cleanup is finished
• Your AI-generated code lands and you need to verify it respects documented boundaries
• The diff is large enough to risk old architectural assumptions sneaking in under new names

Sample Prompts

For a specific feature review:

Do an architectural PR review using PR_TOUGH.md as your constraint.
Review the current state of the [feature-name] work.
Put the output in PR_TOUGH_FINDINGS.md, overwriting if it exists.
Start with findings ordered by severity.

For review immediately after code execution:

You just executed my-feature.md. Now do a tough review using PR_TOUGH.md.
Review [file/directory] for architectural drift against AGENTS.md.
Output to PR_FINDINGS.md.
If CRITICAL, surface it immediately.

For cleanup verification:

Using PR_TOUGH.md, review whether the cleanup claimed in the
commit message actually happened in the code. Check that old
patterns are really gone, not just renamed.
Output to PR_CLEANUP_VERIFICATION.md.

Falling Between the Cracks: The Engineering Terms That Will Kill You

Why boundary violations spread while algorithm bugs stay local, and the five terms that separate muddy architectures from clean ones

The Real Cost of Long-Lived Codebases

Most software pain is not "the loop was wrong" or "the API call failed." Long-lived codebase suffering is almost always:

• Code in the wrong namespace
• Broken boundaries
• Muddy contracts
• Too many entry points for the same behavior
• No clean handoff between responsibilities

Algorithm bugs are local. You fix a loop and one feature works. Boundary bugs spread. You fix canonical truth in one place and six other places still have the wrong copy. That is why the pain feels sticky.

Five Terms That Matter More Than You Think

These are not jargon for its own sake. They are labels for the failure modes that keep costing you time. Understand them and you can prevent entire categories of problems. Ignore them and AI will write code that violates each one, and you will spend months cleaning it up.

1. Namespace — Where Code Lives

Definition: The directory or module where a piece of code belongs. Namespace is about ownership and responsibility, not just file location.

Example: src/session/ owns session lifecycle. src/ui/ owns rendering. src/wt/ owns Windows Terminal integration.

The violation: UI code writing canonical session records. WT code mutating session state directly. Session code doing rendering.

Why it matters: When responsibilities leak across namespaces, you cannot change one part without breaking another. A small refactor becomes an excavation.

2. Boundary — Who May Do What

Definition: The rule about what is allowed to cross between namespaces. A boundary says "this side may call that side, but not vice versa" or "data may flow this direction, but not that one."

Example: UI may call session service. Session service must not call UI. Temporary launch data may not become canonical session state.

The violation: Session code calling back into UI. Temporary state persisting as if it were durable. A boundary that exists in docs but not in code.

Why it matters: Boundaries prevent circular dependencies and make it safe to refactor one side without touching the other. A muddy boundary means you cannot refactor either side without risking silent breakage.

3. Contract — What Is Promised at the Boundary

Definition: The explicit agreement about what will happen when you call a function or cross a boundary. Shape of data, behavior on success and failure, invariants that remain true, side effects that will not happen.

Example: Resolve-Launch returns success only after uniqueness is proven. Launching twice with the same parameters returns the same session key. Canonical records cannot contain temporary fields.

The violation: A function that sometimes writes state, sometimes doesn't, depending on context. Data shapes that change between callers. Success that does not guarantee the promised invariant actually holds.

Why it matters: A broken contract means the caller cannot trust the result. If the contract is ambiguous, tests pass but code breaks in production. If contracts are enforced everywhere, you can reason about the system.

4. Entry Point — Where a Flow Starts

Definition: The specific function or file where a behavior begins. Not just "we handle launches" but "launches begin at Start-ManagedSessionLaunch, and that is the only place where a launch can be initiated."

Example: User launching a session always goes through Start-ManagedSessionLaunch. Platform discovery always goes through Resolve-PlatformSession. Canonical records always created by New-CanonicalRecord.

The violation: Multiple functions that both launch sessions. Three different ways to discover platforms. Canonical records created inline in five places.

Why it matters: If there are multiple entry points, each one becomes a place where assumptions can diverge. One path creates records with field A, another with field B. One path validates, another does not. The more entry points, the more places the contract can break.

5. Seam — The Narrow Handoff Where Behavior Can Be Swapped

Definition: The intentionally narrow place where one responsibility hands off to another, or where behavior can be swapped out, tested in isolation, or refactored without touching anything else.

Example: "Platform-targeted launch resolution" is a seam. The overall launch flow is the same for all platforms. Each platform implements its own targeted query behind the same flow. You can swap the platform query logic without touching the flow.

The violation: The handoff between session behavior and WT transport is not cleanly isolated. Some behavior lives in the wrong place. The old code and new code coexist, and you cannot tell which path runs when.

Why it matters: A good seam lets you replace one part without corrupting others. A muddy seam means every change carries the risk of invisible breakage. Clean seams make testing easier (you can test each side independently) and refactoring safer (you know the boundary will hold).

The Damage Pattern: How These Terms Break Down

In a real codebase with real pain, the failure pattern is almost always this sequence:

This is the cycle that keeps killing long-lived codebases. It is not that the code is badly written. It is that these five boundaries eroded, and now you cannot tell what is safe to change.

How AI Makes This Worse

AI violates these categories with remarkable consistency, especially when unaware of them:

• Namespace violation: "I'll put this helper right where it is called, in the UI file, because it is easier." Now the helper is in the wrong namespace and you cannot reuse it from session code without pulling UI code with it.
• Boundary violation: "UI code needs to update the session, so I'll call the write function directly from the UI handler." Now UI is writing canonical state and you cannot change the canonical storage without breaking UI.
• Contract violation: "This function sometimes returns null, sometimes a partial object, sometimes a full object. The caller will figure it out." Now the caller writes defensive code everywhere and contracts become unreadable.
• Entry point violation: "There are three places that need to launch sessions, so I'll add launch logic in each one." Now launches behave differently depending on which entry point is called, and testing one does not prove the others work.
• Seam violation: "The old implementation and the new one should coexist for now, for safety." Now nobody knows which one runs when, and you cannot retire either one without risking invisible breakage.

What To Do About It

Before AI writes code: Tell it the terms. Define your namespaces, boundaries, and contracts explicitly in CLAUDE.md. Name your entry points. Identify your seams. The clearer you are, the better the AI respects them.

During code review: Use these terms in your review. Do not just say "this looks wrong." Say "this violates the boundary between session and UI" or "this creates a second entry point that will diverge." Be specific about which term is broken.

When the AI proposes helper placement: Ask whether it belongs in the namespace where it is defined, or whether it is masquerading as something it is not.

When cleanup is claimed: Verify that old paths are actually gone, not just renamed. Use the five terms as your checklist.

Future Possibility: Better Than Faster

Today's AI behaves like a very fast implementer, a mediocre architect, and an inconsistent custodian of invariants. It is strong at local tasks: code generation, pattern matching, mechanical refactors, filling in implementation once the shape is clear. It is much weaker at the architectural work: preserving intent across many files, killing old paths instead of extending them, noticing that a "working" shortcut violates a boundary, maintaining discipline when a hack is locally convenient.

The result is useful—faster coding than humans can do by hand. But it also creates a cleanup tax: after implementation, you spend weeks catching boundary violations that were locally convenient at the time, removing old paths that the AI preserved "just in case," and enforcing invariants that the AI ignored when they would have slowed down the code generation.

What Current AI Excels At

• Local code generation within a single file or function
• Pattern matching — recognizing similar patterns in existing code and repeating them
• Mechanical refactors — moving code, renaming variables, restructuring without changing behavior
• Filling in implementation details once the shape is clear — given a function signature and docstring, producing the body

What Current AI Struggles With

• Preserving architectural intent across many files — knowing that a decision made in one namespace should prevent a certain pattern in another
• Killing old paths instead of extending them — actively removing code instead of preserving both old and new ways
• Noticing that a "working" shortcut violates a boundary — recognizing when code that passes tests is architecturally wrong
• Maintaining discipline when a hack is locally convenient — resisting the temptation to violate a boundary because it would make the current task faster

What Would Change Everything

The jump in usefulness would not come from being faster at coding. It would come from being better at architecture:

• Stronger architectural memory. The AI would hold the full model of your namespaces, boundaries, contracts, and seams in active memory throughout implementation. Not as a checklist to read once, but as a constraint that guides every decision.
• Stricter contract obedience. When a contract says "this function must guarantee uniqueness," the AI enforces it everywhere. When a boundary says "this side may not call that side," the AI refuses to cross it, even if crossing would make the code faster.
• Better detection of boundary drift. The AI notices when a shortcut being taken is actually a boundary violation in disguise. It actively surfaces these, rather than letting them pass as "working code."
• Refusal to preserve legacy paths unless explicitly told. When refactoring, the AI removes old code, not extends it. It does not keep the old way "just in case." You get a clean transition, not a muddy coexistence.
• Active protection of invariants even when a shortcut would be faster. The AI sacrifices speed for correctness. It takes the longer path that preserves an invariant, instead of the short path that violates it but lets the tests pass.

With these shifts, the cleanup tax would drop dramatically. Right now, 30–40% of the work after AI implementation is catching and fixing boundary violations, removing preserved old paths, and enforcing forgotten invariants. If AI actively protected those boundaries instead of just respecting them when told, the post-implementation work would shrink to testing, optimization, and integration. That would be a real jump in usefulness—not just faster coding, but cleaner coding that requires less cleanup.

That is not here yet. But it is the gap to watch for in future systems. When you evaluate a new AI tool, ask not "how fast can it code?" but "how well does it understand and enforce my architecture?" Speed is commoditized. Architectural discipline is still rare.

Retrospective: The Real Skill Is Not Writing Rules

It seems the problem is not adding enough guardrails and `.md` rules. The real problem is that you yourself need to know these ideas. The rules help, but only if you can recognize when the model is violating the underlying concept. Otherwise, the model can appear compliant while still drifting.

This is the hard truth: the durable skill is not "write more rules." It is being able to spot the violation yourself.

Can you see when code is in the wrong namespace? Can you spot a boundary leaking across layers? Can you tell when temporary state is being treated as canonical authority? Can you recognize when a contract has gone ambiguous? Can you tell which old paths should have died instead of being preserved?

Once you develop that eye, the documentation becomes a sharper tool instead of fragile hope. Instead of hoping the AI internalized the rules, you actively catch violations as they happen and call them by their true name:

• "No, this is dual authority. Temporary state cannot be treated as canonical."
• "No, this crosses the boundary. UI code must not mutate session records."
• "No, this scratch artifact does not belong in canonical state."
• "Delete the old path. We are not preserving both ways."
• "This violates the contract. The function promised uniqueness. Now it does not."

That feedback is much stronger than handing the AI a rule file and trusting it to internalize the philosophy. It is real time, specific, and tied to the actual code.

The documents matter. They give you a language and a framework. They help you think clearly. But they are not a substitute for developing your own ability to see the patterns. The moment you can recognize a namespace violation or a boundary leak without consulting a rule, the documents stop being your guardrails and become your tools.

That is why these five terms—namespace, boundary, contract, entry point, seam—are worth internalizing. Not because they are clever terminology, but because once you see them, you cannot unsee them. And once you cannot unsee them, you can protect your architecture in real time instead of cleaning up drift afterward.

How to Run a Plan

From competitive planning through disciplined execution — a repeatable process that works

Execute my-feature.md using RUN_PLAN.md as your constraint.
Complete the preflight first, then proceed with implementation.

Execute refactor-auth.md using RUN_PLAN.md.
After implementation, do a tough review using PR_TOUGH.md
and output findings to PR_REFACTOR_FINDINGS.md.

Execute the plan using RUN_PLAN.md.
Write the full Phase 0 preflight to PREFLIGHT.md
and wait for my approval before touching any code.
Do not proceed without explicit go/no-go from me.

# RUN_PLAN.md

Use this prompt when handing an implementation plan to an AI session.
The plan tells it what to change. This document tells it how to execute
with engineering rigor.

This is not a creativity prompt. It is an execution-control prompt.

---

## Execution Prompt

```text
You are executing an implementation plan. Read AGENTS.md (or CLAUDE.md)
first. These files are law and override anything in the plan that
conflicts with them.

Then read the plan file: [PLAN_FILE_PATH]

Do not start coding until you complete the preflight below.

Your job is to make the smallest correct change that:
- still matches the current codebase, not just the plan
- respects the project's architectural boundaries
- preserves data and state coherence
- avoids hidden side effects
- lands with proof through tests and validation

---

### Phase 0: Preflight (No Code Changes)

Before touching any file, do all of the following:

1. Restate the task precisely.
   - Requested outcome
   - Scope (which files, layers, or subsystems)
   - Non-goals (what you will NOT change)
   - Assumptions

2. Read the actual source, not summaries.
   - Read every file the plan names.
   - Confirm the code still matches the plan.
   - If a function moved, changed shape, or was already partially fixed,
     say so before proceeding.

3. Identify the owner and seam.
   - Name the canonical helper or module that owns the behavior.
   - Search before writing. If a helper exists, use it.
   - If no helper exists and the pattern is durable, create it in the
     correct location before using it.

4. Identify the blast radius.
   - For every function you will modify, find every caller.
   - If the contract changes in any way -- parameters, return shape,
     side effects, or behavior -- all callers are in scope for
     validation, even if the plan did not mention them.

5. Identify the test surface.
   - Find existing tests that cover the touched behavior.
   - If no test exists for a new guardrail or transition, plan to add one.
   - If an existing test asserts old behavior that the change replaces,
     plan to update it to the new contract.

6. Build a risk map. Explicitly assess:
   - Architecture and boundary violations
   - Data shape and contract drift
   - Null paths and error propagation
   - Silent failures (skipped items, swallowed errors)
   - Test coverage gaps

7. State the execution order before coding.
   - List the changes in order.
   - Name the file and function for each.
   - If the operator asked for preflight-only, stop here and report.

---

### Phase 1: Implement (One Bounded Change At A Time)

For each item in the execution order:

Before editing:
- Re-read the function you are about to modify.
- Re-read its callers if you are changing its contract.
- Re-read the tests that cover it.

While editing:
- Change the minimum necessary for this item.
- Preserve existing architectural boundaries.
- Do not duplicate helpers or create a second version of an existing
  utility.
- Do not refactor surrounding code unless it is directly required for
  correctness.
- Preserve full object/document shape when mutating data; do not
  rebuild a subset and silently drop fields.

After each item:
- State what changed, in what file and function, and what the
  behavioral difference is.
- If the contract changed, list the callers and confirm they were
  updated or verified.
- Do not move to the next item until this one is internally consistent.

---

### Phase 2: Validate

1. Run the narrowest relevant tests first.
   - Start with the test file or block closest to the changed behavior.
   - Then run the broader test suite for the touched module.

2. Run build validation.
   - [PROJECT-SPECIFIC: insert your build command here]
   - Do not skip build validation because targeted tests passed.

3. Re-check callers and regressions.
   - Grep for every modified function and confirm callers are correct.
   - Confirm no caller is now passing wrong arguments or relying on
     behavior that changed.

4. State manual validation truthfully.
   - If behavior crosses environment-dependent boundaries, state exactly
     what was and was not validated manually.

---

### Phase 3: Self-Review

Before declaring done, review your changes against these defect classes:

1. Architecture drift
   - Did you bypass a helper or cross a boundary?
   - Did you put logic in the wrong layer?

2. Data shape and contract drift
   - Did you create another fallback chain instead of normalizing at
     the boundary?
   - Did you strip fields when mutating an object?

3. Error propagation
   - Can an error escape without proper handling?
   - Did any catch path introduce a secondary failure?

4. Silent failures
   - Did you use continue/skip without warning the caller?
   - Did you return an empty result where an error would be more honest?

5. Test gaps
   - Did you add or change behavior without a test?
   - Did you update tests to rubber-stamp new code instead of asserting
     the real contract?

If you find a real problem in self-review and it is in scope and
low-risk, fix it before reporting. Otherwise call it out explicitly.

---

### Stop Conditions

Stop and surface the issue instead of improvising if:
- The plan no longer matches the code in a material way.
- The correct owner or seam is unclear.
- The change requires guessing about ownership or contracts.
- Validation cannot establish that the change is safe.
- The requested change conflicts with AGENTS.md rules.

When blocked, explain the minimum missing fact or decision needed to
proceed. Do not hide uncertainty behind confident wording.

---

### Completion Report

When done, provide:

1. Understanding
   - Requested outcome, scope, non-goals, assumptions

2. Preflight Findings
   - Current owner/helper/seam
   - Files and callers in scope
   - Main risks identified

3. Execution Notes
   - What changed
   - Any deviations from the original plan and why
   - Any callers updated or verified

4. Validation
   - Exact tests or commands run
   - Build status
   - Manual validation performed
   - What remains unvalidated

5. Residual Risks
   - Only real remaining risks, not generic caution text

6. Closeout
   - Is the requested change done?
   - Is follow-up work needed?
   - Is the work ready for review?

Do not commit. Report completion and wait for explicit commit instruction.
```

---

## Short Prompt

Use this when you want a single-paragraph handoff instead of the full
prompt:

```text
Execute the implementation plan in [PLAN_FILE_PATH] with engineering
rigor. Read AGENTS.md (or CLAUDE.md) first. Before writing any code,
restate the outcome, scope, non-goals, assumptions, owners, seams,
callers, tests, and risks. Read the actual files the plan names and
confirm the plan still matches the code. Search before writing. Use
existing helpers. Preserve architecture and data shape. Implement one
bounded change at a time. Verify callers after contract changes. Run
targeted tests, then build validation. Self-review against the defect
classes. Report changes, validation, and residual risks honestly.
Do not commit without explicit permission.
```

---

## Template You Can Hand to an AI

```text
Task: <one-sentence requested outcome>
Plan file: [PLAN_FILE_PATH]

Read AGENTS.md (or CLAUDE.md) first.

Before coding, produce:
1. Understanding -- outcome, scope, non-goals, assumptions
2. Preflight -- files read, owner/seam, callers, tests, risks
3. Execution Order -- ordered steps, acceptance criteria, validation plan

Then implement conservatively:
- search before writing
- use existing helpers
- preserve architecture and data shape
- add or update tests for changed behavior

After implementation, report:
- what changed, callers verified
- tests and commands run
- build status
- manual validation performed
- what remains unvalidated
- residual risks
```

---

## Engineering Rigor Checklist

Use this to judge whether your plan is strong enough before execution.

| Discipline    | Strong                                              | Weak                                                |
|---------------|-----------------------------------------------------|-----------------------------------------------------|
| Objective     | States what must change AND what must not. Defines acceptance criteria. | Mixes bug fix, refactor, and feature into one blur. |
| Preflight     | AI reads actual files first. Assumes plan may be stale. Forces caller discovery. | Lets AI code from the document without checking the repo. |
| Architecture  | Names owning module/service. Enforces helper-first reuse. | Says "update whatever is needed."                   |
| Data/State    | Names data structures and contracts. Treats shape divergence as a defect. | Assumes data is straightforward.                    |
| Safety        | Maps errors to correct responses. Does not silence failures. | Catches generic errors. Skips items without warning. |
| Validation    | Targeted tests first, then build. Tests error and multi-item paths. | Says "run tests" without naming what proves correctness. |
| Reporting     | Concrete, falsifiable. Records what was and was not validated. | Reports success without evidence.                   |

---

## Unplanned Work

This document works without a plan file. For bug fixes, one-off tasks,
or any work where you don't have a formal plan, substitute the bug
description or task description for [PLAN_FILE_PATH] and skip the
"confirm plan matches code" step -- everything else applies. The
preflight still forces you to find the owner, callers, blast radius,
tests, and data shape before coding. The implementation, validation,
and self-review phases are identical. Use the Template section with:

  Task: fix <description>
  No plan file. Use RUN_PLAN.md methodology.

---

## Why This Exists

AI sessions executing plans fail in repeatable ways:

1. The plan is stale and the AI patches the wrong method.
2. The plan names the function but not the callers -- blast radius missed.
3. The AI creates a new helper instead of using the one that exists.
4. The AI rebuilds a subset of fields and silently drops the rest.
5. The AI updates tests to rubber-stamp new behavior instead of the contract.
6. The AI fixes the symptom but not the root cause.
7. The AI says "done" without proving the change.

Every phase in this template exists to block one or more of those
failure modes.

while ! task_complete; do
  output=$(claude --print "$(cat PROMPT.md)" 2>&1)
  echo "$output" >> session.log
  update_prompt "$output"
done

Embarrassing Case Study

how not to do it, so you can learn how to do it

What Happened

One Saturday morning, coding away, I had too many AI console windows open and couldn't tell which was which. So I thought to put watermarks on the background — when I switched between consoles, I'd see the context. The rest of that day was that program. By the end of it I had v1 and v2 fully coded and was already using it. I shared it around at work, made a GitHub for it, and built an installer. This is the story of that program.

When you see v1 through v8 in the graph below, keep in mind: each check-in was a coding session and a version number, and I could do multiple versions in a day. This is a real story.

The tool was built fast. v1 through v8 added platforms, features, and integrations at high velocity: Claude Code, then Codex, then Copilot, then OpenCode, then Gemini, then Kiro. A Jira integration. GitHub PR review. Cost tracking. Windows Terminal profile management. A companion maintenance utility. A build pipeline. IP-protection obfuscation. All of it in roughly 10 weekends of active development.

By v8.3.0 the product worked. It had users. It had real commercial value. It also had the accumulated debt of every shortcut taken in the name of shipping the next feature.

The v9 arc was the reckoning. Not a rewrite — a systematic repair of every pattern that had been done wrong or duplicated across files. It ran from v9.0.0 through v9.9.8, across more than a dozen focused increments, and it cost more lines than all prior development combined.

The Graph That Started This Conversation

All 98 commits aggregated by major version. Each block represents a relative change wave. v8.x excludes the obfuscated build artifact.

v9 is not close. Scores of change sets across 45 commits, dwarfing all prior eras combined. That bar is the architecture investment made visible.

The Architecture Tax

Project: A multi-platform AI session manager for Windows Terminal
Language: PowerShell 5.1
Timeline: 10 weekends
Commits: 98 total
The question this case study answers: What does it cost when you skip architecture on day 1?

The Specific Patterns That Were Retrofitted

Each v9 task addressed a class of problem that was avoidable on day 1:

Variant logic scattered across files. Every supported platform had its behavior hardcoded in whichever file happened to need it first. Adding a new platform required touching seven files. v9 introduced a central registry: one structure, all variant behavior, zero hardcoding elsewhere.

Raw I/O everywhere. Owned data files were read and written directly with no atomicity, no backup, no error handling. A crash mid-write meant silent data corruption. v9 introduced canonical read/write helpers that all managed files route through — the only place in the codebase allowed to touch owned data files directly.

External system mutations without transactions. Operations that modified an external system's config read it, mutated it in memory, and wrote it back directly. A failure mid-operation left the external system in a broken state invisible to the user. v9 wrapped all such mutations in a transaction pattern: read, modify in memory, write atomically, validate, restore on failure.

Entity identity with no documented precedence. A key entity's display name could be derived from multiple sources, each with its own priority. Each code path had its own inference logic. When they disagreed, the entity showed the wrong name. v9 established a single canonical function with a documented precedence order called by all display, repair, and rename code. The bug had been latent since v1.

Test infrastructure that tested the wrong code. The test suite was stitched into the same artifact as the production code. Several tests matched by string search in a way that found their own test definitions before the actual production functions. Tests were silently passing while the code they were supposed to protect had real violations. v9 fixed the matching logic, revealing six tests that had been producing false results for months.

Orphaned artifacts from failed operations. When a multi-step operation failed partway through — after some artifacts were created but before the operation completed — the partial artifacts remained permanently. Users would find ghost entries they never created. v9 introduced artifact cleanup tracking: record each creation, clean up everything created so far in the catch block before rethrowing.

Duplicate ceremony in every entry path. Multiple code paths each had their own copy of the same 15–20 step sequence. When one copy got a bug fix, the others did not. v9 extracted all shared steps into helper functions called by every entry path.

"A Rewrite Would Have Been Easier"

Looking at the graph, that thought is natural. Here is the direct answer.

What the v9 change sets actually contain: A significant portion are tests. A rewrite needs tests too — written without the knowledge of which edge cases fail in production. Many are planning documents. The largest individual commits are largely refactoring churn: the same lines deleted from one location and added to another. A function that moves between files costs double in the diff. The real net change is zero.

What a rewrite would actually cost: Five Windows Terminal integration surfaces, each with non-obvious quirks. Five platform data formats reverse-engineered from live data. All discovered knowledge. A rewrite starts from zero. Most importantly: a rewrite is done under the same pressure that created the original architecture problems. The impulse to ship features beats the impulse to do it right. That is exactly what happened in v1 through v8.

Where the observation is correct: The v9 arc was more expensive than it needed to be because it happened after the product shipped instead of before. The canonical helpers, registry-driven dispatch, atomic writes, and red-green testing that v9 established would have cost a fraction of what they cost at v9 if they had been the founding architecture. The graph is the receipt. The question it should prompt is not "should we have rewritten?" but "what would we have said on day 1?"

The Actual Cost

At standard software engineering rates ($150–200/hr senior developer), the v9 arc represents:

• 45 commits over a concentrated sprint of focused work
• Estimated real developer hours: 60–100 hours
• At $175/hr: $10,500 — $17,500 to retrofit architecture that cost nothing to establish

The same 12 rules, put in place on day 1, would have taken perhaps 2 hours to write and would have been enforced automatically by the AI assistant with every subsequent code generation. The entire v9 arc — every refactor, every bug it revealed, every test it required — would not have been necessary.

That is the cost of skipping architecture on day 1.

What the Product Looked Like After

At v9.9.8, the codebase passed a zero-violation code review against 29 mandatory architectural rules. The test suite had 640+ tests across 30 files, with named validation bundles for CI/CD integration. Adding a new AI platform required zero changes to rendering, dispatch, WT profile management, or image generation — one registry entry and the platform-specific discovery function. Session lifecycle errors left no orphaned artifacts. Windows Terminal mutations rolled back automatically on failure.

The v9 arc was not a mistake. It built a product that can grow without collapsing. The mistake was not having the architecture from the start.

The Day-1 Prompt

This is a template CLAUDE.md — a complete architectural ruleset you would paste at the start of your project, before the first line of code. Every rule comes from something that actually broke in production. Fill in your project details below and download a ready-to-use file.

↓ Full template for reference — fill the <placeholders> manually if you prefer:

You are building <YourProduct> -- <one sentence description of what it does>.
Before writing any code, the following architectural rules are non-negotiable. Every
decision you make must be consistent with them. When in doubt, ask before deviating.

---

RULE 1: <YOUR VARIANT DIMENSION> REGISTRY IS THE ONLY SOURCE OF TRUTH FOR VARIANT BEHAVIOR

All <variant>-specific values live in a single central registry structure in one file.
No other file may hardcode a <variant> name, identifier, or behavior as a literal.
When you need <variant>-specific behavior, read it from the registry.
When adding a new <variant>, add one registry entry. Zero other files change.

This rule exists because <variants> will be added continuously. If variant logic is
scattered, every new <variant> is a surgery. If it is in the registry, every new
<variant> is a data entry.

---

RULE 2: ALL READS AND WRITES TO OWNED DATA GO THROUGH CANONICAL HELPERS

<YourProduct> owns several data files. Every read goes through Read-DataSafe.
Every write goes through Write-DataAtomic, which writes to a temp file and renames
atomically so a crash mid-write cannot corrupt data.

Never read or write owned data files directly anywhere else in the codebase.

External data owned by other systems may use raw reads, but any writes to external
config must still use an atomic write helper. Document the reason at each raw-read site.

---

RULE 3: ALL MUTATIONS TO <EXTERNAL SYSTEM> GO THROUGH A SERVICE LAYER

Any operation that modifies <external system state> must call a function in the
<system> service layer. No file outside that layer may read or write <external system
state> directly.

The service layer must wrap mutations in a transaction: read current state, make the
change in memory, write atomically, validate the result. On any exception, restore the
backup. This is not optional even for "simple" changes. Silent corruption is invisible
until users hit it.

---

RULE 4: <KEY ENTITY> IDENTITY HAS ONE CANONICAL PRECEDENCE ORDER, ENFORCED IN ONE PLACE

<Entity> display name resolution:
  <source A>  >  <source B>  >  <fallback>

These rules are implemented in exactly one function each. All display code, all repair
code, and all rename code calls those functions. No file infers <entity> identity
through its own logic. When this rule is violated, <entity> shows the wrong name or
links to the wrong record.

---

RULE 5: SOURCE CODE IS ORGANIZED INTO NAMESPACES. EACH NAMESPACE OWNS ITS CONCERNS.

  src/core/        -- global state, persistence helpers, <variant> registry
  src/<domain A>/ -- <domain A> lifecycle operations
  src/<domain B>/ -- <domain B> operations
  src/ui/          -- rendering, display, navigation
  src/integration/ -- external service clients
  src/testing/     -- all test code (never included in production builds)

A file in one namespace must not implement another namespace's logic. Cross-namespace
dependencies create phantom coupling: changes in one area break unrelated areas silently.

If a function's home is not obvious, it belongs in core/ as a shared helper.

---

RULE 6: THE REPO ROOT STAYS CLEAN

The repo root contains only:
  - Primary entrypoints and launchers
  - Primary compiled or stitched artifacts
  - Canonical instruction and index documents (CLAUDE.md, AGENTS.md, README.md, <docs-index>)
  - Major source and support directories

Build machinery belongs in build\ or equivalent.
Launcher wrappers belong in Install\ or equivalent.
Planning docs, one-off notes, and screenshots do not belong at the root.
Temporary files placed at the root during development must be cleaned up before commit.

---

RULE 7: DOCUMENTATION HAS DEDICATED NAMESPACES

docs/ is organized into stable subfolders. Every durable document belongs in exactly one:
  docs/<product-docs>/   -- user-facing docs and release history
  docs/<planning-docs>/  -- backlog, plans, and future ideas
  docs/<reference-docs>/ -- architecture, data models, and reference material
  docs/<process-docs>/   -- AI workflow, review standards, and comment standards
  docs/<assets>/         -- images and media used by docs

Do not place new documents loose in docs/ without a namespace.
Any durable new document must be placed in a namespace and linked from <docs-index>.

---

RULE 8: NEW TOP-LEVEL DIRECTORIES REQUIRE JUSTIFICATION

Create a new top-level directory only when all three are true:
  - The content does not fit any existing namespace
  - It represents a real subsystem or product boundary
  - Top-level placement improves clarity more than nesting would

Default to using an existing namespace. The burden of proof is on the new directory.

---

RULE 9: THE BUILD SYSTEM IS MULTI-PRODUCT FROM DAY ONE

If you ship more than one artifact from this codebase, each has a manifest listing
the source files to include in order.

When you add a source file: update all manifests or document why it belongs to only one.
When you move a function: check every manifest.
When you add a shared helper: include it in all manifests that need it.

Failing to maintain manifests silently breaks one product while the other works.

---

RULE 7: EVERY BUG FIX IS PRECEDED BY A FAILING TEST

Before fixing any bug: write a test that reproduces it and fails. Then fix the bug.
Then confirm the test passes. The test is not optional.

Bugs fixed without tests return. A test that explicitly reproduces a bug is
documentation that the bug was real, proof that the fix is correct, and insurance
that the fix stays correct.

Use string-literal test identifiers, not sequential numbers. Sequential numbers
require renumbering when tests are inserted. String literals survive reordering.

---

RULE 8: EVERY FUNCTION THAT CREATES ARTIFACTS MUST CLEAN THEM UP ON FAILURE

If a function creates any persistent artifact -- a record, a config entry, an external
system object -- and anything goes wrong before the function completes, all created
artifacts must be removed in the catch block before rethrowing.

Track artifact creation with boolean flags:
  artifactCreated = false
  ... create artifact ...
  artifactCreated = true
  ... on exception ...
  if (artifactCreated) { remove artifact }

Artifacts left behind by failed operations accumulate silently and confuse users.

---

RULE 9: EXTRACT SHARED HELPERS AT THE SECOND INSTANCE, NOT THE THIRD

The first time you write a pattern inline, that is acceptable. The second time you
write the same pattern in a different file, extract it into a shared helper first.
Do not wait for three instances.

When duplication reaches three or four instances, the fix requires touching every
instance. When caught at two, the fix is cheap.

---

RULE 10: NO EMPTY CATCH BLOCKS. NO SWALLOWED EXCEPTIONS.

Every catch block must either:
  a) Log the exception to a debug/error log, or
  b) Re-throw after performing cleanup, or
  c) Return a structured error result that the caller checks

An empty catch is a bug. Swallowed exceptions cause functions to return success when
they have failed and users to see wrong state with no indication of what went wrong.

---

RULE 11: RUNTIME COMPATIBILITY IS A HARD CONSTRAINT, NOT AN AFTERTHOUGHT

This tool runs on the user's machine. Specify your minimum runtime and test against it.
Do not use language features or library calls that require a newer runtime than your
stated minimum. New syntax that silently degrades on older runtimes is the hardest
class of bug to diagnose.

---

RULE 12: THE <KEY OPERATION> LIFECYCLE HAS ONE CANONICAL SEQUENCE

Every path that triggers <key operation> follows the same sequence of shared steps:

  1. Resolve <variant> and configuration from registry
  2. Resolve or generate <entity> identity
  3. Create or acquire required resources
  4. Execute the operation
  5. Confirm and record the result
  6. On any exception: release/remove all resources acquired in steps 3-4

These steps are implemented as shared helper functions called by all entry paths.
No entry path owns its own version. When steps are implemented multiple times, each
copy drifts. When one copy gets a fix, the others do not.

---

RULE 13: COMMENTS DESCRIBE CURRENT TRUTH, NOT HISTORY OR INVENTORY

File headers must contain: File, Namespace, Purpose, and optional Notes.
File headers describe ownership and invariants -- not a list of every function.
Function inventories in file headers are forbidden. They go stale immediately and
mislead both humans and AI about what the file actually does.

When a refactor changes a file's responsibility, update the file header in the same
commit. Not later. Not in a cleanup pass. In the same commit.

Use function-level documentation blocks (.SYNOPSIS, docstrings, JSDoc, xmldoc --
whatever your language provides) for detailed behavior. File headers describe
boundaries. Function blocks describe contracts. Neither does the other's job.

Comments must describe current truth, not historical intent. If a comment describes
something that was true in v3 but is not true now, delete it. History belongs in
git log and CHANGELOG -- not in source files.

A stale comment is worse than no comment. It will mislead the next developer -- and
it will mislead your AI, which reads comments as instructions.

---

WHY THESE RULES EXIST

Every rule above addresses a specific class of production bug or refactoring cost
that compounds over time. None are style preferences. Each rule was written because
something broke in production without it.

These rules do not slow development. They slow the first implementation of each
pattern by a few minutes. They prevent the class of incident where a single missing
cleanup call costs two engineering weeks to diagnose six months later.

Hold to them from the first commit.

Tests Are the Exoskeleton

The single most important observation about AI-developed software.

Tests aren't quality hygiene in this context — they're the only thing that gives the AI memory of what the system is supposed to do.

A human developer carries architectural intent in their head. When they change module A, they remember module B depends on it. An AI has no such memory between sessions. It only knows what it can see — and in a large codebase, it can't see everything. Tests are the exoskeleton that holds the shape of the system while the AI works inside it.

A codebase at 11% test coverage has no exoskeleton. Each change may be correct in isolation and wrong in the system. There's no way to know.

A production codebase with 800+ tests caught 400+ bugs before they shipped — that isn't just a quality metric, it's proof that the bugs existed and would have reached users. That's not a hypothetical benefit. That's 400 production failures that didn't happen.

Tests That Know What the Architecture Is

The corollary worth noting: the best test architecture is itself registry-aware. Static analysis tests scan for hardcoding violations — meaning the tests don't just verify output, they enforce architectural contracts. When the AI tries to shortcut the registry pattern, a test fails. The discipline is self-reinforcing in a way that no amount of code review can replicate.

From Vibe Coding to Engineering

This website is a personal discovery journey. I was amazed how much I learned just in the Advanced: Building a Plugin section I added, and how it demystified the architecture of Claude even more. I also realized as I wrote and took the quizzes that I had been using AI incorrectly. This site was changing my view of AI.

I admit, I used to think that if I did Claude Code and made apps through vibe coding, that I was an AI engineer — the proof was in the amazing apps I wrote (with one in the Chrome store, and loads of tools written for work). Alas, having done that, and trying to fix an app that I made, I realized that I was unwittingly doing it wrong. I wasn't coding with Claude correctly, and yet I was getting great results. And by the time I got to version 5 of one of my projects, it started collapsing. I am on version 10 now, mainly refactors — leading to the creation of this Manifesto. I have spent more time refactoring that app (still broken) than I did making it. That is why I stepped back, and rethought how to avoid that trap. I had to learn how to do this right, and I am still learning.

To call myself an AI Engineer (as I did) was a false sense of power from early success with AI prompting. And I saw non-engineers having the same successes (even greater!), with no engineering discipline. However, as I made this manifesto, I realized that engineering is possible through AI tools — if the hooks, agents, skills, memory and plugins are used properly. If a person is vibe coding with good results, I want them to join me in rethinking the engineering aspects. I could have saved myself so much time if I followed the patterns learned from my career as a software engineer.

Claude Code is like a loaded gun: you can point it at an animal and have a meal, or you can shoot your own foot. Consider this site to be a gun safety course and weapons training. The quizzes are important, as they reinforce learning. I'll keep vibe coding (I didn't engineer this site, I vibe coded it), but there is a time to engineer.

In all honesty, engineering is not my goal. Immediate and powerful solutions have drawn me to AI (and Claude Code in particular). I can have a great app in 10 hours? Yes! But in that fever-pitched drive to a solution, I had a flaw. The flaw was in my thinking. I thought Claude was something it isn't. That is why I stepped back, studied Claude more closely, and wrote this site. I hope the manifesto does its work on you too. My problem was not bad prompting, but bad thinking, and I can't ignore engineering, because I needed to re-engineer my own thoughts. Ironically, our underlying subject is software that emulates human thinking, and as you correct your thoughts about AI, you are engineering the only biological brain you can change.

For more, I point you to this interactive tutorial on the early history of AI, with videos: github.com/srives/Perceptron

The New Epistemology

A philosophical retrospective on what AI programming is doing to the programmer.

I am building up a mental model of what programming is becoming. The black CLI screen, the text prompt, the running agent inside the repository: these are not incidental surfaces. They change the way the work feels. The terminal is spare, verbal, procedural, and immediate. It is less like arranging objects in an IDE and more like addressing a machine intelligence in its own workshop.

That changes the programmer. The tool affects the thing it is designed to affect, but it also affects the practitioner. A hoe cuts the soil and raises blisters on the hand. LLM/CLI programming cuts through boilerplate and raises blisters in the mind.

At first there is pain. Then the calluses form. The callus is not numbness. It is trained sensitivity.

The Medium Works Back

McLuhan's line was that the medium is the message. The related lesson is that we shape our tools, and then our tools shape us. AI-assisted programming makes that literal. I prompt the model, but the model's habits teach me what I must become more precise about.

When I build now, I often do not see code first. I see blocks of intention: stores, boundaries, contracts, lifecycle flows, entry points, invariants, and seams. Handwritten code can feel small because it is local. The mental object is larger than the line. The line is only one visible trace of the object.

From Files to Stores

The word "file" names a physical artifact. The word "store" names a responsibility. A store is durable state with rules: where it lives, who may read it, who may mutate it, how writes are made atomic, how failure rolls back, and what shape must remain true afterward.

That shift matters because AI is often locally helpful and globally careless. It will write the direct file access if the direct file access solves the immediate problem. It will place a helper where it is convenient. It will preserve an old path "for safety." It will let two sources of truth coexist if nobody forces the question of ownership.

The new discipline is to ask, before the code appears: who owns this state? What boundary is being crossed? What is the one canonical path? What invariant must survive the edit?

Seams and Boundaries

A seam is the narrow handoff where one responsibility gives way to another. It is the place where behavior can be swapped, tested, or refactored without corrupting the rest of the system. A good seam preserves future freedom. A muddy seam destroys it.

This is why boundary bugs feel different from algorithm bugs. An algorithm bug is local. A boundary bug spreads. When canonical truth exists in two places, fixing one copy does not fix the system. When three entry points perform the same lifecycle differently, testing one path proves almost nothing about the others.

The Mental Blisters

The New Unit of Thought

The Blind Potter

I feel like a blind potter. The clay is no longer directly under my hand. It is behind a curtain, and I feel it through delayed signals: diffs, test failures, logs, runtime behavior, and architectural drift. Yet the cup can still be made. The bowl can still be shaped.

The millions and billions of tokens are the pounds of clay wasted while learning where the form is. They are not just cost. They are apprenticeship. The waste teaches touch.

The Token Apprenticeship

Tokens are not the real unit of learning, but they are a useful metaphor. The real unit is repeated, painful failure classes.

• Awe: The output appears. The speed feels like proof.
• Pain: The product works, but repair becomes confusing. "Working" and "engineered" separate.
• Vocabulary: Failures get names: boundary violation, stale path, duplicated source of truth, missing test, wrong owner.
• Callus: Durable controls appear: AGENTS.md, CLAUDE.md, RUN_PLAN.md, tests, hooks, review prompts, architecture rules.
• Second order: The programmer stops merely prompting the AI and starts designing the environment that shapes the AI's behavior.

One brutal project can teach more than millions of pleasant tokens. The fast build gives power. The refactor gives epistemology.

A Practical Discipline

The next leap is not only to model what the AI builds. It is to model how the AI tends to fail.

1. Name the failure class.
2. Decide whether it is local or architectural.
3. Add a rule only if the failure class will recur.
4. Add a test if the rule can be enforced mechanically.
5. Add a seam if future change needs protected freedom.
6. Add memory only for facts the next session must inherit.