AI Native software engineering
A plain-English guide to building software with AI agents: what the model is, how it reads your codebase, and the tools, permissions, and review discipline that turn it into something you can ship.
A field guide by James Phoenix
Working in an AI-native way starts with understanding what the agent actually is. Not a colleague and not a search engine, but a language model wrapped in a loop that can read files, run commands, and edit your code. Almost every surprising thing these tools do makes sense once you see the machinery underneath.
This guide walks that machinery end to end: the model and the tokens it reads, the context window it all has to fit inside, the agent loop and the tools that give it hands, the permissions that decide what it may touch, and the failure modes worth watching for.
The map below groups the vocabulary into a handful of areas, each linking through to plain-English definitions in the dictionary. Below that are the field notes: essays where I put these ideas to work on real systems.
Every entry is typed, so you can tell a practice from a failure mode at a glance: 12 patterns, 5 antipatterns, and 52 concepts.
The areas it covers
The full vocabulary is organised into these areas. Skim them for the shape of the field, then open any one for its definitions.
Foundations
The base layer: what a model is, how it turns text into tokens, and why the same prompt can give different answers.
Browse the 9 terms →Providers & requests
How a coding agent actually talks to a model: the harness, the request, and what you pay for on the way in and out.
Browse the 9 terms →Context
Everything the model can see for a single request, and the moves you make to keep it useful as work grows.
Browse the 9 terms →Agents & tools
The loop that turns a chat model into something that reads files, runs commands, and edits your codebase.
Browse the 10 terms →Permissions & safety
The guardrails that decide what an agent may touch, and when a human has to say yes.
Browse the 5 terms →Knowledge & failure modes
What the model knows, where that knowledge ends, and the predictable ways it gets things wrong.
Browse the 8 terms →Context engineering
Deliberately shaping what goes into the context window: memory, specs, handoffs, and progressive disclosure.
Browse the 10 terms →Workflow & practice
How people actually work with agents day to day, from vibe coding to review discipline.
Browse the 9 terms →From the notes
The dictionary above defines the parts. These are the field notes: essays where I work through how those parts fit together once you are actually building with agents, not just reading about them. Start anywhere, each one stands on its own.
The harness and the environment
The setup around the model matters more than the prompt. These are about the scaffolding that turns a language model into something that ships.
- Building the Harness Around Claude CodeClaude Code harnesses a model; here is how you harness Claude Code in turn.PatternProven
- The Execution Harness That Lets Agents Ship CodeWhy determinism, schema isolation, and enforced layering are the real agentic-coding unlocks.PatternProven
- The Sandbox Is a HarnessHow a sandbox stops being a security fence and becomes a tool for intent.PatternValidated
- The Environment Leads The AgentWhy fixing repo boilerplate steers an agent better than ever-cleverer prompts do.PatternProven
- Generator-Evaluator Harness Design: Anthropic’s GAN-Inspired Architecture for Long-Running AppsSplitting generation from evaluation, a GAN-inspired shape for long-running agent apps.PatternValidated
Loops that run on their own
Agents get useful when the same small loop runs over and over without you holding its hand.
- The RALPH LoopA fresh context each pass, with memory kept in git, docs, and task files.PatternProven
- Loop EngineeringA durable loop needs three parts: a trigger, a bounded runner, and a gate.PatternProven
- Autonomous Loops Need a Scoring FunctionWithout a scoring function a loop is chaos, not hill-climbing toward better code.PatternValidated
- AI Daemons: Persistent Background Agents for Operational DebtPersistent background agents that quietly pay down operational and maintenance debt over time.PatternEmerging
Many agents at once
What changes when you run several agents in parallel instead of one at a time.
- Sub-Agent Architecture: Specialized Agents for Higher Quality CodeSplitting work across specialized sub-agents to isolate concerns and raise code quality.PatternProven
- Contracts Parallelize AgentsDefine the contract between agents first, then dispatch them concurrently rather than in sequence.PatternValidated
- Orchestration Patterns: Coordinator, Swarm, and PipelineThree ways to coordinate multiple agents: coordinator, swarm, and pipeline.PatternValidated
- Git Worktrees for Parallel Development: 3x Throughput with AI AgentsUsing separate worktrees to run parallel agent sessions without context-switching costs.PatternProven
- Sub-Agent Swarm Convergence: Why Swarms Converge or ExplodeWhy a swarm of agents reduces system error instead of amplifying it.Concept
Review and verification
Trusting code you did not write by hand is the new job. These are the guardrails that make it safe.
- AI Code ReviewScaling how hard you review by the blast radius of the change.PatternProven
- The Verification LadderTypes, schema, unit, property, formal: each rung catches what lower ones miss.PatternProven
- Claude Code Hooks as Automated Quality GatesWiring hooks to run linters, type checks, and tests on every tool call.PatternProven
- Quality Gates as Information Filters: Reducing State Space Through VerificationSeeing each gate as an intersection that shrinks the space of possible outputs.PatternValidated
Designing for agents, and the shift in the work
The longer arc: building software, config, and habits for a world where agents write most of the code.
- Agent-Native ArchitectureDesigning software where AI agents are first-class citizens, not later bolt-ons.PatternValidated
- Writing a Good CLAUDE.mdWhat belongs in a CLAUDE.md: WHY, WHAT, HOW, kept deliberately minimal.PatternProven
- Rewrite Your CLI for AI AgentsOptimising a CLI for agent predictability and defense-in-depth, not human discoverability.PatternValidated
- Developers Are Having an Identity CrisisA calmer reframe of the engineer identity crisis that AI-assisted coding set off.Concept
Context engineering
The deeper discipline underneath: deciding what a model sees. Retrieval, agent patterns, reliability, and evaluation, each with a runnable example.
Go to the guide →Common questions
What is AI native software engineering?
It is building software with AI coding agents as a first-class part of the workflow, not an occasional autocomplete. You work through a model wrapped in a loop that can read files, run commands, and edit code, so most of the skill moves into the harness, the context you provide, and the review around the output rather than typing the code yourself.
How is it different from vibe coding?
Vibe coding means accepting whatever the agent produces on feel, which is fine for prototypes and throwaway tools. AI native software engineering keeps that speed but adds the discipline that makes the output safe to ship: verification, automated checks, scoped permissions, and a human who takes responsibility for the change.
Do I still need to read the code the agent writes?
Yes. Agents pass the coding threshold, but judgment does not transfer with it. You scale how hard you review by the blast radius of the change: a config tweak gets a glance, a change to auth or billing gets read line by line. Review is the core skill now, not typing.
What is a harness?
The harness is the code wrapped around the model that builds requests, runs tools, manages context, and enforces permissions. It is the agent minus the model, and it is where most of the real engineering lives. A good harness is what turns a capable model into something that reliably ships.
What is the agent loop?
The loop is the cycle that turns a chat model into an agent: it takes your request, calls tools to read files or run commands, reads the results, and decides what to do next, repeating until the task is done. The model supplies the judgment, and the loop and its tools give it hands.
Which model or tool should I use?
It matters less than the harness and the context you give it. Pick a strong current model, then spend your effort on the environment: clear repo structure, conventions written down in a CLAUDE.md or AGENTS.md, and automated checks the agent can verify against. The setup around the model beats swapping models.
Will AI coding agents replace software engineers?
They replace the typing, not the engineering. The work shifts from writing every line to specifying intent, shaping the environment, and reviewing output you did not hand-write. The coder role shrinks and the role that decides what to build, and whether it is correct, grows.
How do I get consistent results from a model that is not deterministic?
You do not rely on the model being consistent, you make the system around it consistent. Constrain the task with a spec, give it examples, and gate every result behind automated checks that either pass or fail. Determinism lives in the harness and the tests, not in the model.
What are subagents, and when should I use them?
A subagent is a separate agent that the main agent spawns to handle a scoped subtask with its own fresh context. It does the work, returns a short result, and the noise of how it got there never touches the main conversation. Reach for one when a task is self-contained and would otherwise flood the main window.
How do I run agents safely without them breaking things?
Give them least privilege. Decide which actions run automatically and which need your approval, keep destructive commands behind a permission prompt, and run risky work inside a sandbox that limits what the filesystem and network can reach. Safety is a property of the environment you set up, not of the model.
Can I let an agent run unattended?
Only with strong guardrails. Running away from the keyboard is safe when the agent has automated checks it must pass, a bounded loop, and a scoring function that tells it whether it is getting closer. Without those, an unattended agent drifts. With them, it can hill-climb toward a working result on its own.
What is a CLAUDE.md or AGENTS.md file for?
It is a project file of standing instructions and conventions that the agent loads at the start of a session. It gives a repo its own memory: why the code is shaped the way it is, what to do, and how, kept deliberately short. It is one of the highest-leverage pieces of context you can write.
How do several agents work in parallel without colliding?
You isolate them. Git worktrees give each agent its own working directory, and clear contracts between the pieces let them work on separate parts without stepping on each other. Define the interface first, then dispatch the agents concurrently and merge when each one passes its checks.
How do I verify code an agent wrote?
With a ladder of checks that get stricter as the stakes rise: types, then a linter, then unit and property tests, then a build, and a human read at the top. Each rung catches what the ones below miss. The point is to make correctness something the machine can prove, not something you hope for.
What skills matter most now that agents write the code?
System thinking, clear specification, and review. Knowing what to build and how to describe it, shaping an environment an agent can work in, and being able to read a change and judge whether it is right. Syntax recall matters less; taste and judgment matter more.
Where should I start?
Start by understanding the machinery: the model, the context window, the agent loop, and the tools. Then set up one repo well with a short instructions file and automated checks, and drive a real task through it end to end. The map above links each idea to a definition, and the field notes show it applied.
Want this applied to your product?
The dictionary is how I think out loud. If you want that thinking turned into a working system for your team, that is what I do.
See how I can help