I recently got the chance to build a new system from scratch. Seizing the opportunity, I've been working AI coding agents like Claude Code hard the whole way through.
The speed at which code gets written has gone up to an almost comical degree. Work that used to take days is taking shape by the time I'm back from lunch. And yet, as things moved along, a certain unease crept in. Maybe there are things a human should decide before letting AI write the code.
Things like the directory layout, the API design, the shape of error responses. Leave those undecided, and the AI will pick whatever implementation looks most reasonable at that moment. That in itself isn't bad. But there is no guarantee that the same instruction on a different day will produce the same structure. Switch from Claude Code to Codex, and the odds get worse.
Think of it as a building site where a different carpenter shows up every day. Every one of them is skilled. Without blueprints, though, Monday's carpenter builds a tatami room and Tuesday's puts a double-height atrium right next to it. Each room is fine on its own; the house as a whole is incoherent. If the design shifts every time the implementing AI changes, long-term maintainability is a lost cause.
So I wrote down what I want settled at the start of a new project. To be clear, I'm not saying every project should use the same stack. What matters, I think, is making the criteria for decisions explicit, and building mechanisms that keep them honored over time.
Building on the same lot
First, if there are multiple applications, I want a monorepo. Something like this:
apps/
web/ # React SPA
admin/ # Admin console
api/ # Go API
docs/ # Docusaurus
packages/
api-client/ # Client generated from OpenAPI
shared/ # Shared libraries
Frontend, backend and documentation all live in one repository. Easier code sharing and reviewing related changes together are the classic benefits. When developing with AI, there's another: related specs and implementation are all visible from the same workspace. When an API spec changes, being able to update the OpenAPI definition, the backend and the frontend types in one go is quietly very handy.
That said, a monorepo doesn't tidy up the design by itself. Building on the same lot doesn't settle which building is allowed to lean on which. Dependencies between applications and the responsibilities of shared packages need rules of their own.
One contract: OpenAPI
When the frontend and backend are developed separately, I'd rather not maintain API types twice. So OpenAPI becomes the single source of truth for the API contract. From the OpenAPI definition, I generate:
- Go request and response types
- Go server interfaces
- TypeScript type definitions
- An API client for the frontend
oapi-codegen for Go and openapi-typescript for TypeScript are the likely candidates. Neither side has to write its own types anymore.
But the real win isn't the generation itself. It's being able to set a development rule: every API change starts with OpenAPI. When I ask AI to add an API, it first edits the OpenAPI definition, then implements against it. It's the habit of fixing the blueprint before shouting instructions at the carpenter.
Generating types doesn't guarantee the implementation matches, of course. Request and response validation and contract tests are still needed. Eventually I'd like CI to catch breaking changes in the OpenAPI definition, too.
One way to fail
Error responses are a surprisingly common thing to put off. Build without deciding anything, and each endpoint sprouts its own error format.
{"error": "Not Found"}
{"message": "Resource not found", "code": 404}
Both get the point across. But it's the frontend that ends up absorbing the difference. So I adopt RFC 9457 (Problem Details for HTTP APIs).
{
"type": "https://example.com/problems/not-found",
"title": "Not Found",
"status": 404,
"detail": "The specified resource does not exist"
}
The Content-Type is application/problem+json. Now error responses are consistent across the whole API. Not having to design a custom error format from scratch is a bigger deal than it sounds.
Let the files draw the floor plan
Personally, the decision that paid off most this time was file-based routing. In a React SPA you can define routes directly in code. On the other hand, libraries like TanStack Router support file-based routing.
routes/
index.tsx
login.tsx
users/
index.tsx
$userId.tsx
settings/
index.tsx
When the file layout mirrors the URL structure, there's no question where a new screen goes. It's like having the floor plan painted directly on the floor.
As it happens, when I suggested file-based routing to the AI, it replied that "with so few screens at this point, the benefit is small." Looking only at today's screen count, that's a fair call.
But implementation cost today isn't the only thing I care about. What I want is for the structure to come out the same no matter which AI adds the next screen.
That's because, in the past, I asked AI to add a page and found it had quietly created the page inside thecomponents directory. With no rule about where screens go, the AI presumably picked whatever spot made the most sense in the moment. It's like asking for a living room and finding the carpenter built it inside the storage shed. Rearranging routing after development is well underway is worse than laying down the rule at the start. That was my call.
Of course, file-based routing doesn't sort out every responsibility. How screens, components, business logic and API access are separated should be decided as well.
Rules you follow without noticing
From here on, the topic is how to make the rules stick.
ESLint, Prettier and TypeScript type checking are often set up automatically now when AI scaffolds a project. Adopting them takes far less effort than it used to. But having the tools isn't the point. The point is a state where developers and AI alike follow the rules without having to think about it. Here's what I want as standard:
- Code checks with ESLint
- Formatting with Prettier
- TypeScript strict mode
- Lint and type checks in CI
- A unified set of formatting rules
Mind you, ESLint and Prettier were set up this time because the AI helpfully added them on its own. These days there are also Rust-based alternatives like Oxlint and Oxfmt, and they perform far better. When I migrated a different project, linting got about 37x faster and formatting about 91x faster (how I moved from ESLint and Prettier to Oxlint and Oxfmt). If checks run often, the shorter the wait, the better.
If needed, I also restrict dependencies between directories;dependency-cruiser and similar tools can verify this. Rather than just telling the AI "don't import from this directory," I want a machine to notice when it does. A wall you physically can't walk through beats a note left for the carpenter.
Relying on people to run checks by hand will slip sooner or later. So I add Husky and automate the checks with Git hooks. A division of labor might look like this:
| Timing | What runs |
|---|---|
| pre-commit | Lint and format via lint-staged |
| commit-msg | commitlint |
| pre-push | Type check, unit tests |
| Pull Request | Lint, type check, all tests |
Running every test before each push grinds development to a halt, so heavy integration tests and E2E go to CI. Besides, Git hooks can be skipped if someone really wants to. The last line of defense has to be enforced in CI.
Commit messages get standardized too. I go with Conventional Commits.
feat(auth): add Google login
fix(api): handle validation errors
docs(adr): document API design
refactor(web): simplify user form
test(api): add integration tests
Combine Husky with commitlint and nonconforming commits get rejected. Commit messages have always tended to vary by author. If AI is writing the commits too, unifying the format matters even more. The history can then feed CHANGELOG generation and release management.
Clearing away the offcuts
One thing that bothers me in AI-driven development is the buildup of dead code. AI is enthusiastic about adding features, but it won't necessarily clean up files and functions that a refactor made obsolete. The carpenter builds new shelves fast, then leaves the old ones standing.
So I bring in Knip. It mainly detects:
- Unused files
- Unused exports
- Unused dependencies
- Undeclared dependencies
Monorepos in particular tend to accumulate shared code and packages nobody uses anymore. That said, some mechanisms, like file-based routing and code generation, can't be judged from static references alone, so the config needs tuning. Personally, I think running Knip in CI or during periodic maintenance, rather than on every commit, is about right.
Granularity over volume
Ask AI to "write tests" and you can get a mountain of test code back. But more tests don't necessarily mean higher quality. Checking how many times an internal function was called, or that a trivial getter works, won't necessarily catch bugs in the business rules that actually matter.
So I want to decide test granularity up front.
| Type | Main targets |
|---|---|
| Unit Test | Business logic, calculations, validation |
| Integration Test | DB access, APIs, authentication and authorization |
| Contract Test | Consistency between OpenAPI and the API implementation |
| E2E Test | Critical user flows |
Add an API handler, write an integration test. Add business logic, write a unit test. If it's an important feature users interact with, consider E2E. The goal is that looking at a change tells you which tests it needs.
Rather than chasing a coverage number, I care that important specs and edge cases are verified. And when a bug is fixed, there should be a rule to add a regression test so it doesn't come back.
A logbook for after the accident
Logging is easy to forget in a new project. During development the priority is getting things to work, and designing the information needed for incident investigation gets pushed back. But adding logs after something breaks in production is too late. At a minimum, I want these decided up front:
- Structured logs in JSON
- Clear use of INFO, WARN, ERROR and so on
- Request IDs for tracing
- Recording the cause and target when errors occur
- A rule against logging personal data or secrets
- Log retention and monitoring policy
slog does the job.
logger.Error(
"failed to create user",
"request_id", requestID,
"error", err,
)
What matters is being able to trace what happened after an error. If the request ID is threaded through the entire API, incidents spanning multiple operations become much easier to follow. Rather than leaving logging to the AI's mood, I want to decide up front what gets recorded and where.
The blueprints, and why they were drawn
I also want specs and design documents managed from day one. This time I'm going with Docusaurus. The docs live inside the monorepo and are versioned in Git alongside the code.
apps/docs/
docs/
architecture/
api/
development/
adr/
Developers can browse the specs on the documentation site. Meanwhile, AI like Claude Code and Codex can read the Markdown straight from the repository. In other words, humans and AI are looking at the same blueprints. When docs live somewhere other than the code, people forget to update them and the two drift apart. As much as possible, spec changes and doc updates should land in the same pull request.
The finished docs get hosted on something like Cloudflare Pages. On Cloudflare's free tier, a small project costs next to nothing. Add Cloudflare Access and you have an authenticated documentation site. Access can be limited to a Google Workspace email domain or specific allowed addresses, so there's no need to build authentication yourself.
Allowing all of@gmail.com, though, is far too wide a gate. You need appropriate conditions, such as specific addresses or your organization's domain. It's also worth checking the free tier's user and usage limits in advance.
Technology decisions get recorded too. Why Go? Why a React SPA? Why not a web framework like Gin? To be able to look back on these choices, I write ADRs (Architecture Decision Records).
adr/
0001-use-monorepo.md
0002-use-openapi.md
0003-standardize-api-errors.md
0004-use-file-based-routing.md
Each ADR records three things:
- Context: why the question came up
- Decision: what was adopted
- Consequences: what impact it has
This pays off especially when developing with AI. Without knowing past discussions, AI will cheerfully re-propose technologies that were already considered and settled. It's the new carpenter asking, "How about an atrium here?" With ADRs, the reasoning can be checked on the spot. And I think it's important to record not only why something was adopted, but why something wasn't.
Notes for the carpenters
The rules decided so far should live somewhere AI can read them. That's whatAGENTS.md and CLAUDE.md are for. The content might look like this:
# Development Rules
## API
- OpenAPI is the source of truth for the API contract
- Update OpenAPI first when adding or changing APIs
- Errors follow RFC 9457
## Frontend
- Use file-based routing
- Use the generated API client
## Testing
- Add unit tests for business logic
- Check contract tests when the API changes
- Add a regression test when fixing a bug
## Architecture
- Review existing ADRs
- Update the ADR when changing a technology choice
Writing it in a document for AI doesn't mean it will always be followed, though. Notes get skimmed. Humans do it too, so it would be unkind to blame only the AI. Whatever can be verified mechanically should be verified with linting and CI. Combining written instructions with mechanical constraints is the key.
And all these tools are just decoration if they never run. Use something like GitHub Actions to run automatic checks on every pull request. A setup might look like this:
Pull Request
|
+-- Lint / Format
|
+-- Type Check
|
+-- Unit Test
|
+-- Integration Test
|
+-- OpenAPI Contract Check
|
+-- Knip
|
+-- Security Scan
|
+-- Build
|
+-- E2E Test
|
v
Review / Merge
Where it makes sense, I'd also add secret detection with tools like Gitleaks and dependency updates with Renovate. The important thing is that AI-written code and human-written code go through the same checks. Don't just tell the AI "always run the tests"; build an environment where failing tests block the merge. A house that fails inspection doesn't get handed over, no matter who built it.
Choosing not to build
I've lined up a lot of tools here, but I don't think everything should go in from the start.
What matters isn't using well-known technology but being able to explain why you use it. Deciding not to adopt something is a perfectly respectable architectural decision. The rooms you chose not to build are part of the blueprint too.
AI is changing how software gets built. Writing code has become cheaper, and features can be added faster than ever. But the design and quality of generated code don't line up on their own. For a system meant to run for years, you have to think not only about today's speed but about the day another developer, or another AI, touches it. To that end, here's what I want to keep in mind:
- Decide design rules first
- Keep the rules as documentation
- Verify automatically with tools wherever possible
- Record the reasons for technology choices in ADRs
- Keep the same design principles even when the AI changes
From here on, the question won't just be how much code you can get AI to write, but how well you can build an environment where AI keeps writing high-quality code.
So that's the groundwork for getting a house built by a different carpenter every day. Skilled carpenters now show up every morning. That's exactly why drawing the blueprints remains a human job. Precisely because we hand implementation to AI, humans need to set the design rules first. This new project drove that home for me all over again.