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.

It also covers the part that gets skipped until something goes wrong. An agent with access to your code, exposure to text an attacker can write, and a way to reach the network is the lethal trifecta, and no amount of careful prompting closes it. What does help is least privilege, egress control, and scaling review by blast radius: properties of the environment you build, not of the model you chose.

If you want to know where your own team currently sits, the AI-Native Engineering Assessment is twenty questions that return the autonomy level your repository can safely support, and the one thing holding you there. It takes about six minutes and nothing leaves your browser.

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 77 terms in the AI Coding Dictionary

Every entry is typed, so you can tell a practice from a failure mode at a glance: 14 patterns, 10 antipatterns, and 53 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.

Reading paths

Where to start

The dictionary is organised for looking things up, which is unhelpful when you do not yet know what to look up. These are ordered paths through it. Pick the one that matches why you are here and read it front to back; each is roughly an evening.

Start here: what an agent actually is

For: New to coding agents, and want the machinery rather than the marketing

  1. ModelThe thing at the centre: a file of numbers that continues text.
  2. TokenThe unit everything is measured and billed in.
  3. Context windowThe hard ceiling every decision has to fit inside.
  4. AgentA model wrapped in a loop. This is where autocomplete becomes something else.
  5. ToolHow a text predictor gets hands.
  6. HarnessThe agent minus the model, and where most of the engineering lives.
  7. Non-determinismWhy the same prompt gives different answers, and why that is not a bug.
  8. Building the Harness Around Claude CodeThe whole picture applied to a real setup.

Directing agents day to day

For: Using an agent already, and want better output from it

  1. SpecThe single highest-leverage input. Vague request in, vague change out.
  2. AGENTS.mdStanding instructions so you stop repeating yourself every session.
  3. Writing a Good CLAUDE.mdWhat actually belongs in one, kept deliberately short.
  4. Progressive disclosureLoad context when needed instead of dumping it up front.
  5. Automated checkThe gate that either passes or fails, with no opinion involved.
  6. Blast radiusHow to spend review attention where it matters.
  7. Human reviewThe part that does not transfer, and why.
  8. AI Code ReviewScaling review effort by consequence rather than reviewing everything the same.

Securing an agent

For: Giving an agent real access, or about to

  1. Lethal trifectaThree ingredients that turn a helpful agent into an exfiltration route.
  2. Prompt injectionWhy data and instructions sharing one channel is structural, not a bug to patch.
  3. Least privilegeThe one defence that works without knowing how the attack arrives.
  4. Egress controlUsually the cheapest leg of the trifecta to remove.
  5. Tool poisoningInstalling an MCP server means accepting text into your system prompt.
  6. Sandbox escapeAlmost never an exploit. Usually a mount or a credential that was inside all along.
  7. Agent trapContent written for an automated reader rather than a human one.
  8. AFKWhy all of the above matters most when nobody is watching.

Running agents unattended

For: Want a loop that makes progress while you are asleep

  1. HarnessNothing runs unattended without this being solid first.
  2. Automated checkThe only judge available when you are not there.
  3. The Verification LadderTypes, schema, unit, property, formal. Each rung catches what the ones below miss.
  4. The RALPH LoopFresh context each iteration, memory in git rather than the conversation.
  5. Autonomous Loops Need a Scoring FunctionWithout one, a loop is a chaos engine.
  6. Loop EngineeringA loop is engineered, not launched: trigger, runner, gate.
  7. AFKWhat has to be true before you walk away.
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.

Can an agent be tricked by a web page or file it reads?

Yes, and this is the failure mode to understand before giving an agent real access. A model receives your instructions and the content it retrieves through the same channel, so text in a web page, a dependency README, or even a stale code comment can be read as instruction. It is called prompt injection, and it is structural rather than a bug to be patched: a defence written in the same channel as the attack is not a boundary.

What is the lethal trifecta?

It is an agent having three things at once: access to private data, exposure to untrusted content, and a way to communicate outward. Any two are usually survivable. All three mean someone who can influence what the agent reads can, in principle, get your data sent somewhere. The useful part is that it turns "is this safe?" into three checkable questions about a tool configuration, and removing any one leg collapses the worst case. Cutting outbound network access is usually the cheapest.

Is it safe to install MCP servers?

Treat each one as accepting text into your system prompt from whoever wrote it. Tool names, descriptions, and parameter docs are all serialised into the context and read with the same weight as your own instructions, so a tool description can instruct the model. Read the definitions once before installing, pin versions so they cannot change silently, and keep tool access scoped so a poisoned description has nowhere useful to go.

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