What is in this

AI can write the code. The harder problem is handing it a codebase where the right change is obvious, the wrong change gets caught, and a person can approve the result without reading every line.

That is a property of the project rather than of the model, and a migration is a good time to build it in.

What actually goes wrong

Ask an agent to change a headline and it finds the same copy in four components and changes one. Ask for a new page and it invents a route shape that exists nowhere else in the project. Ask it to fix one layout and it edits a shared component that quietly changes twelve other pages.

The code it wrote may be perfectly valid. What went wrong is that the repository did not make the intended change obvious, and nothing downstream caught the one it made instead.

A developer new to the project hits the same wall. Neither a person nor an agent reliably stops when uncertain, and both can ask. What decides the outcome is whether the uncertainty is visible: whether the project states which pattern applies, which components are shared, and what has to be checked before a change is proposed.

The repository should explain itself

A site should have a small number of recognizable patterns. A marketing page has one shape, a collection entry has another, a paginated listing has a third.

When somebody asks for a new page the question should rarely be how to build it. It should be which of the existing patterns this is, and there should be one of each to copy.

The same applies to components, to content and to integrations. Where there are five ways to do one thing, every contributor has to guess which one belongs here, and half of them guess differently.

Content should not hide inside components

A headline is usually content, and it usually belongs in the content system rather than inside an Astro or React component.

Be careful about what that buys. Content kept in the repository still goes through a commit and a review, so moving copy out of a component does not by itself remove the pull request. What it removes is the implementation change: the edit stops being a code edit and becomes a content edit, which is a smaller thing to review. A configured CMS goes further and separates publishing from deployment entirely, so the marketing team changes a sentence without anybody opening the project.

Either way the boundary is the useful part. Content changes go through the content system. Structural changes go through the repository. An agent is then left with the work that genuinely is code.

Give the agent instructions for this project

Every repository worth handing over explains its own rules, in a file the team's tools actually read.

Where that file goes depends on the tool. Some read `AGENTS.md`, some read their own project-instruction file, some read neither unless configured. Put it where the tool you use discovers it, then check that it did, because an instruction file nothing reads is a document rather than a control.

It does not need to be long. It needs to answer what an unfamiliar developer would otherwise reconstruct by reading everything.

# Project instructions

## Structure
- Route patterns and one example of each: page, collection entry, paginated listing.
- Content lives in Sanity. Components live in src/components.
- Shared components are listed; changing one changes every page that uses it.

## Before changing shared behavior
- Find the pages that consume the component.
- Check representative pages at phone and desktop width.

## Verification
- `npm run build` runs the site build and eight checks after it.
- Name what each check enforces, so a failure is readable.
- Report any check that failed or did not run. Do not work around one.

## Boundaries
- Dependencies, integrations and redirect rules need a second look.
- Content edits go through the CMS, not the repository.

Agents should propose changes, not quietly ship them

Repository access is not production access. The useful arrangement is the one a new developer gets, and the enforcement is the part that matters: a pull request on its own enforces nothing. Required status checks, a required approval and a restriction on who can bypass them are settings somebody has to turn on, and on GitHub they live in branch protection.

The rules themselves deserve the same scrutiny as the code. A change that edits the checks, the approval requirement or the workflow that runs them is a change to the gate rather than a change behind it, and it should be read that way.

The human stays the approval boundary. What should change is what they spend the review on: the diff in front of them, rather than reconstructing the whole project every time a pull request opens.

How a proposed change reaches production

Agent proposes

Against the repository, the instructions and the content model, on a branch of its own.
Branch and pull request

Opening one enforces nothing on its own. The enforcement is in the settings below.
Required checks and a preview

Configured as required, so the merge button is unavailable until they pass.

A failing check stops it here
Required human approval

A named reviewer, with bypass restricted to people who should have it.

Revised or declined here
Merge and deploy

And a way back: what reverses this if it turns out wrong.

The exits are the point. A sequence drawn as a straight line says every proposal ships, which is the opposite of what a review step is for. And the settings that create these stops are themselves a thing somebody can change.

Test the finished website, not just the code

A build passing tells you the project compiled. That is a real check and it is not nothing, but it does not tell you that a page still renders, that a redirect still resolves, that a form still reaches the CRM or that a shared component did not break another route.

The checks worth having on a marketing site assert things about the finished site. Every expected route renders. Every old address resolves to its intended destination. Internal links point at something real. Required metadata exists. Forms reach the system they are meant to reach. Important pages have not quietly become noindex.

Those are cheap to specify during a migration, because the route list, the redirect map, the content inventory and the integration behavior all have to be established anyway. How cheap they are to automate varies: a route crawl is an afternoon and a reliable form-destination check, with a test environment that does not pollute the real CRM, can be considerably more.

Proposed change	Evidence to inspect	What it does not prove
Add an article route	The expected address renders the intended article	That anything the article says is accurate
Change a shared layout	Representative consuming pages, at the widths that matter	That every content combination survives it
Update a redirect	The status code and the final destination, requested directly	That rankings hold
Modify a form	A marked test record arriving with its required fields	That every failure of the external service is handled

The right column is the part people skip. A check that passes is evidence about one thing, and reading it as evidence about everything is how a green build ends up meaning nothing.

What this has to do with a migration

None of this requires Astro.

A well-run team can do all of it to the repository they already have, and if your current site works this way, changing frameworks to become AI ready would be a poor reason to move.

What a migration offers is timing. Before a site can be moved, somebody has to establish every route, every content type, every integration, every redirect, every shared component and every behavior that has to survive. That is close to the same inventory these properties are built from, and collecting it twice is the expensive way to do it.

A migration that ends with routes nobody can explain, copy scattered through components and no checks worth failing has moved the website without making it easier to own.

What this does not buy you

An agent-ready repository does not make agents reliable. They still misunderstand requests, pick the wrong abstraction and write code you would not have written.

What structure and checks change is what happens next, and only for the mistakes they were built to catch. A change that touches a shared component is easier to see in a diff. A route that stops rendering fails a check that exists. Neither guarantees that every wrong change is visible, or that reversing it is cheap, because the ones that get through are by definition the ones nothing was watching for.

That is a smaller claim than the one on most landing pages. The question worth asking is not whether an agent can edit the site, because most can. It is whether you can safely review what it changed.

Take this with you

What to ask of the repository you are handed

Each one is answerable by looking, and each one decides whether the next change is cheap or expensive for whoever makes it.

How many kinds of route are there, and where is one of each?

A small stated set gives a new page an obvious pattern to copy. A route per requirement makes every addition a decision.

Worry if you hear It depends on the page.
Where does a headline live?

In the content system, changing copy is an editorial change. Inside a component it is a code change, reviewed as one.

Worry if you hear Just search for the string.
What tells an agent how this project works, and does its tool read it?

Instructions have to sit where the tool discovers them. One nothing reads is a document rather than a control, and it is worth checking which.

Worry if you hear It is probably in the readme.
What is actually required before a merge?

A pull request enforces nothing by itself. Required checks, a required approval and a restriction on bypassing them are settings somebody turned on, or did not.

Worry if you hear We open a PR for everything.
What do the checks verify beyond compiling?

Compiling is a real check and an incomplete one. It says nothing about a route that stopped rendering, a redirect that loops or a form that stopped arriving.

Worry if you hear It builds clean.
What may an agent change, and what needs a second look?

Content, components, dependencies, integrations and the deploy do not deserve the same level of trust, and the checks themselves least of all.

Worry if you hear It has access to the repo.
How would a wrong change be noticed and reversed?

Structure makes some mistakes visible and some recoveries cheap. It does not make every mistake either, which is why this question has to be asked directly.

Worry if you hear We review everything carefully.

Also worth reading

Reach out and see if we are a good fit.

Get in touch

Currently booking two to four weeks out.

What makes a site safe for an agent to change