The field guide

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.

Browse all 69 terms in the AI Coding Dictionary

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 dictionary

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.

Field notes

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.

Many agents at once

What changes when you run several agents in parallel instead of one at a time.

Keep reading

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 →
FAQ

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