Teaching agents an existing application

The problem

Demonstrations of AI coding usually start from an empty repository. Real organisations start from an application with years of decisions in it: a vendored core nobody may modify, generated metadata that must never be edited by hand, business rules that exist only as behaviour, and customer instances that each differ slightly. An agent that does not know those things will produce plausible changes that break them.

The consequence

The failures are not dramatic. A generated file is patched by hand and silently reverts on the next generation. A calculation is fixed in one module and duplicated in another. A deletion that looked like tidying removes records a customer relies on. Each is a small error that a long-serving engineer would not make, repeated at the speed of an agent.

The approach: context before change

In the organisation described on this site, the answer was to give agents the same context an experienced engineer has, in a form a session can read, and to enforce the few rules that must never be broken.

• Written knowledge the agent reads first. Catalogues of the data model, business rules, codebase and services are regenerated from the estate. A shared memory holds dated rulings and lessons. Anthropic’s own guidance on Claude Code recommends giving the agent this kind of project context.
• The source of truth made explicit. Generators produce the application’s metadata from specifications, and provenance marks every generated artefact. The rule is to fix the generator, never the output.
• Guard rails where the agent acts. Runtime hooks refuse direct database writes, hand edits to generated files and autonomous deletion of records, and each refusal names the tool to use instead.
• Established code brought under the same governance. Existing modules were taken over with their specifications and tests, not rewritten, so their behaviour is protected by the same checks as new work.

The evidence

The guard rails are exercised, not decorative: runtime hooks logged more than 30,000 refused agent actions, recorded on a single workstation, most of them attempts to write straight to the database or hand-edit generated files.

The boundary

Written context goes stale. A catalogue regenerated on a partial copy of the estate once held about half the tables of a complete one, and was caught only because counts were compared. Context helps only as long as it is kept current and checked.

What to do next

Before letting an agent change an existing application, list what a new engineer would need to be told in their first month. Write the answers where the agent will read them, and turn the two or three rules that must never be broken into checks that refuse the action. The architecture handbook shows how the knowledge is organised here.