I establish architectural direction before asking a coding agent to generate features at scale. What it repeats will shape the codebase. I’ve seen this pattern repeatedly in my own work and in serious case studies: teams that establish a sound foundation make later development easier; teams that generate first spend too much time reconciling incompatible choices.
In early experiments with Claude Code, I asked it to generate complete features before establishing shared patterns. The results worked in isolation and were difficult to integrate with the existing codebase. Each new feature seemed to make different choices about how things should fit together.
A reference feature should show the complete path you want an agent to extend: receiving input, applying rules, obtaining data and forming a response. I want its tests to make the shared behavior explicit before asking for another endpoint. You can choose a sound existing feature or build one with assistance and review it. What matters is that its behavior and structure are worth repeating.
September 2026 update: This revision clarifies the Sora case and adds the tested API example and current instruction-file guidance.
Give the agent a foundation worth repeating
OpenAI’s Sora Android account describes engineers establishing architecture, modularization, dependency injection, navigation, authentication and networking, then writing representative features and documenting patterns. They estimated Codex wrote 85% of the project.
They also tried the broad prompt: "Build the Sora Android app based on the iOS code. Go." They quickly abandoned that experiment: the code technically worked, but the product experience and reliability fell short.
Their reasoning: "The idea was not to make 'something that works' as quickly as possible, rather to make 'something that gets how we want things to work.'"
September 2026 availability note: OpenAI reports that Sora became unavailable on April 26, 2026. The engineering account above describes its 2025 Android build.
Think of a senior engineer joining your team. They know how to code, but they need to learn your conventions, error-handling philosophy and product priorities. Examples show how those decisions fit together. An AI can use the preferences and context you supply; you still need to decide which patterns should guide the work.
"Build this settings screen using the same architecture and patterns as this other screen you just saw" gives a reference. "Build a settings screen" leaves conventions open. The fuller Sora Android case study examines the team’s architecture and parallel work.
The patterns I establish manually
When starting an AI-assisted project, I build a foundation by hand before asking the agent to extend it:
Project structure. Where do files go? How are modules organized? What’s the naming convention? I create the directory structure and put a few real files in place.
Core abstractions. I establish the base classes, interfaces or types that other code will extend. For an API, that includes request and response patterns. For a CLI, it includes the command structure. These decisions set the shape of what follows.
One complete feature. I implement a real feature across the relevant layers, from database to API to UI when applicable. It shows how the parts connect.
CLAUDE.md with explicit patterns. I document the conventions with specific examples that an agent can use during the work.
Test patterns. I establish the assertions, fixtures and test organization. One well-written test file gives the next implementation a useful example to extend.
The time investment
As a planning guide, I allow roughly 10–20% of project time for the foundation. On a four-week project, that might be three or four days of manual work before increasing AI generation. The temptation is to generate immediately and fix problems as they arise. But inconsistent patterns compound: each feature adds integration work, and debugging code that fights the rest of the system takes longer than establishing a coherent foundation.
Readiness is more useful than a calendar quota. Before expanding the work, I want to be able to trace the reference feature and run checks that distinguish its intended behavior from plausible mistakes.
What goes in CLAUDE.md
I keep a project CLAUDE.md with four kinds of guidance:
Architecture overview. A concise account of what the project does and how its parts fit together.
Explicit patterns. The state-management choice with an example; the error-handling pattern with code that demonstrates it.
File organization. Where new files belong, the naming convention and how modules relate.
What not to do. Approaches we considered and rejected, including plausible designs that don’t fit this system.
I update the file as the project evolves. When the same mistake recurs, I make the missing guidance explicit. Claude Code’s instruction documentation explains which project files load and when. Put enduring project guidance where the client loads it, check the applicable settings, and inspect whether the implementation follows the chosen patterns.
The package here contains a reference endpoint that returns one note and a completed extension that lists notes by tag. It is a constructed local example. Its JavaScript has been executed; no separate Codex or Claude Code session was asked to implement the brief.
Run the reference and extension
Download the complete example. It requires Node.js 24 or later and no package installation.
unzip reference-feature-example.zip
cd reference-feature-example
node --test example.test.mjs
node check.mjs
The tests ran on Node 24.19.0 and 26.8.2. All nine test groups passed on both versions. The standalone checker reported:
PASS all: 11 HTTP cases (complete)
The test programs start temporary servers on 127.0.0.1, make real HTTP requests and close their servers after use. The records are synthetic and stored in memory. No database, account or external endpoint is needed.
The server uses Node's built-in HTTP API. The example concentrates on request validation, response shape and error behavior; it does not implement persistence or authorization.
Trace one complete request
The reference route is GET /notes/:id. A request for note 1 returns status 200 with this body:
{
"data": {
"id": 1,
"title": "Review the interface",
"tags": ["work"]
}
}
| File | Responsibility in the reference path |
|---|---|
app.mjs | Match the HTTP route, decode its ID and write the JSON response. |
service.mjs | Validate the ID, request the record and distinguish a missing note. |
repository.mjs | Find the synthetic record and return a copy. |
errors.mjs | Turn declared failures into the error envelope and unexpected exceptions into a generic 500 response. |
Read the path through those files. For example, getNote, the service method for the reference feature, requires a positive decimal integer without leading zeros, within JavaScript's safe integer range. It then calls the repository's findById method. A missing record becomes a declared 404 error, handled by the same response path as other failures.
This source review establishes where the responsibilities sit. The HTTP tests establish what callers observe for the tested cases. A different internal arrangement could produce the same responses, so passing those assertions cannot replace the architectural review.
State what the addition must share
The extension is GET /notes, with an optional tag query parameter. It changes the result from one record to an array while keeping the success and error envelopes.
The full task is in extension-brief.md inside the download. It names the files to inspect, the behavior to add, the placement of transport and application logic, and the evidence to return. Its acceptance cases include:
| Request | Required result |
|---|---|
GET /notes | Status 200; all three records in data, in seeded order. |
GET /notes?tag=work | Status 200; notes 1 and 3 in data. |
GET /notes?tag=absent | Status 200; data is an empty array. |
GET /notes?tag= | Status 400 with INVALID_TAG. |
GET /notes?tag=Work | Status 400 with INVALID_TAG. |
GET /notes?tag=work&tag=work | Status 400 with INVALID_QUERY. |
The tag grammar is a lowercase ASCII letter followed by up to 31 lowercase letters, digits or hyphens. That is a choice for this example, made explicit so a new implementation cannot silently choose different treatment for empty or uppercase tags.
Here is the complete list method from service.mjs; the surrounding module is in the download:
async listNotes(rawTag) {
if (rawTag !== null && !/^[a-z][a-z0-9-]{0,31}$/.test(rawTag)) {
throw new HttpError(400, 'INVALID_TAG', 'Use a lowercase tag of 1 to 32 characters.');
}
return repository.listByTag(rawTag);
},
The route passes null when the tag is omitted. The repository then returns all records. With a valid tag, it selects matching records. The transport adds the same data envelope used by the reference feature.
The task brief also asks for the implementation diff, commands actually run and observed results. Those give the reviewer something to check against the original request.
Make an incorrect extension fail
The download includes a deliberately incorrect variant in bad-extension.mjs. It leaves the reference service method untouched but returns the list inside an extra items object. The resulting response puts an object in data where the contract requires an array.
Run its reference checks:
node check.mjs --scope reference --variant bad-extension
The observed result was exit 0:
PASS reference: 3 HTTP cases (bad-extension)
Then run acceptance for the whole addition:
node check.mjs --variant bad-extension
That command deliberately exits 1. Its error begins:
FAIL all (bad-extension): GET /notes body
This failure shows why keeping the original endpoint working is insufficient evidence for accepting a new one.
The expectations in contract.mjs are literal response objects. They do not import the repository's seed data or the application's response helper. Changing the producer therefore does not automatically change what the checker expects. Review changes to those expected objects as contract changes, with a reason for each one.
Check the failure path too
Both features are tested with a repository method that throws an exception containing a synthetic internal-detail string. The HTTP assertion requires status 500 and this JSON body:
{
"error": {
"code": "INTERNAL_ERROR",
"message": "The request could not be completed."
}
}
The internal exception detail is absent from the response. The tests exercise the real routing and shared error mapper; they do not call the mapper directly and assume the endpoints use it.
A success-only example leaves the next task's failure behavior undecided. Include the failures the new feature must handle, then inspect whether its implementation reaches the same agreed error path.
When a reference needs attention
Watch for four signs that the foundation needs work:
Inconsistent patterns. Different features handle the same problem differently. State management, error handling and naming vary without a reason.
Integration friction. Generated components don’t connect smoothly. Adapting them takes more effort than implementing a coherent design would have.
Repeating the same corrections. You fix the same issue in each new feature.
Debugging unfamiliar code. The generated feature works, but you can’t explain how. When it breaks, you have to learn its design from scratch.
If successive changes need the same correction, compare the reference feature, its instructions and the new implementation. Does one endpoint send errors through the shared mapper while another invents a new shape? Are equivalent checks in different layers? Trace one mismatch before extending that pattern again.
These differences can reflect an unclear reference, stale guidance or an implementation that did not follow the agreed design. Inspect the actual diff and request path to distinguish those possibilities. Stop generating more features while you repair the pattern, document the decision, and then resume with a foundation worth extending.
Foundation-first in an existing codebase
An established system may already contain the foundation you need. Select a sound feature and review it before treating it as a reference. Document how the codebase is organized, its key conventions and what a contributor needs to know before making changes. Making those decisions explicit lets an agent extend an architecture the team understands.
For your next task, identify the reference feature by path and revision. Explain which conventions the addition must share and which behavior it may change. Include the specific inputs and expected outputs that decide whether it is complete.
The package’s AGENTS.md states its enduring conventions. OpenAI’s Codex instruction-discovery documentation, checked September 27, 2026, describes global and project guidance, overrides and size limits. Confirm which instructions the intended session loads, then review their application in the code.
Accept the extension after its own acceptance cases pass, the reference behavior still passes, and source review confirms the agreed division of responsibilities. If you cannot explain why a changed expected response is correct, resolve that decision before accepting the patch.
Foundation work establishes the direction for everything an agent will multiply. Humans choose the architecture and the standards; a well-prepared reference helps turn those decisions into consistent implementation. That is why I make the investment before scaling the work.
This article is part of the synthesis coding series.