Vibe Coding Field Notes

A year later, in February 2026, Karpathy gave the professional version a different name: agentic engineering. You write the code yourself perhaps 1% of the time, orchestrating agents who do the rest and acting as oversight; “engineering” because there is art, science and expertise to it. In practice, “vibe coding” increasingly means this, and that is the sense used here.

The data shows why the oversight matters.

AI now writes code that runs remarkably well. But whether it matches the right spec, whether it is safe, and whether it contradicts earlier decisions is not guaranteed unless you make it so. The bigger the system, the more that gap costs.

The point is that each is read at a different moment. Cram it all into AGENTS.md and the agent reads everything every time, which, as last issue's research showed, makes results worse.

The tooling has matured. Two representative examples:

The names differ; the substance is almost identical: three documents, spec, plan and tasks, in a folder per feature, with a person checking each stage. Two points matter most.

• Include a stage where the AI asks questions — like Spec Kit's clarify, have the AI read the draft spec and list what is still undecided. A hole in the spec costs more the later it turns up
• One spec per feature — Kiro's own guidance is to split by feature (authentication, product catalogue, cart…) rather than write one monolith. The smaller each one, the more likely both AI and humans actually read all of it

You don't need the tools: the same folders and Markdown files made by hand work with any agent. The layout in the next chapter is tool-agnostic.

Take an internal order-management system: around 30 screens, a front end, an API and a database, used by purchasing, sales and finance. The repository is laid out like this:

Five principles behind the layout:

• Keep what is always read thin; let on-demand material be thick — AGENTS.md is the entrance and the rules. Details live in docs/ and specs/, and AGENTS.md points to them
• A numbered folder per feature — numbering 012, 013 records order and history, and maps neatly onto branch names and PRs
• Decisions go in ADRs, with reasons — “why PostgreSQL”, “why approval is a state machine”. When an agent starts redesigning on its own, this is what you point to
• Scope area rules by path — API rules load only when the API is touched, not every session
• Never write the same thing twice — rules link to docs. Copies drift, and one of them goes stale

The entrance, AGENTS.md, might look like this. Unlike last issue's example, it makes the process itself a rule: no spec, no build.

Where each tool keeps these:

Let's add an order-approval flow to the system and follow it from spec to verification: six stages, with a human signing off at three of them.

STEP 1 Write the spec (spec.md)

A person writes the purpose and acceptance criteria, because only people know the business context. Then have the AI read it and ask: “what is still undecided?”

Write acceptance criteria so they can become tests as they stand. Not “easy to use” but “¥500,000 or more goes to awaiting approval”. When each condition maps to one outcome, both the AI and a person can judge it in step 5.

STEP 2 Plan it (plan.md and an ADR)

The AI drafts the plan; a person decides. Check that it doesn't break the existing structure or contradict earlier decisions. Decisions that are hard to reverse, such as how state is held, go in an ADR.

STEP 3 Break it into tasks (tasks.md)

Make each task small enough to finish in one exchange and check once done. The trick is to put the test-writing task before the implementation.

STEPS 4–6 Implement, verify, close the spec

• Implement — work down tasks.md one item at a time. One task per commit means you always know where to roll back to. Hand broad investigation (mapping the blast radius, say) to a subagent so the main conversation stays clean
• Verify — “tests, types and E2E pass” is the definition of done, enforced in CI. Human review compares against the acceptance criteria before reading the diff. Check security explicitly, missing permission checks and XSS above all; as chapter 1 showed, left alone nearly half slips through
• Close the spec — write back what was decided along the way (no deputy approver, say) so spec and code agree. A spec that has drifted will steer the AI wrong on the next feature

Rules are requests. Anything that must always hold belongs in hooks or CI. As Claude Code's documentation puts it, writing “never edit .env” is a request, not a guarantee; if a rule must hold every time, make it a hook. Here is a hook that runs lint after every file edit:

This table follows Claude Code's own advice to build your setup gradually. You don't need all of it on day one.

And three things to avoid:

• Having the AI write one giant spec in one go — a spec nobody can read through is a spec nobody has checked
• Committing AI-written documents unread — as last issue's research found, auto-generated instructions left as they are make results worse
• Calling it done because it works on screen — “works”, “correct” and “safe” are three different things

Tools and names will keep changing. What is here is the common ground of the official guidance from Spec Kit, Kiro, Claude Code and Cursor, restated so it doesn't depend on any one tool.