Why This Stage Decides Agent Quality
Same model, same codebase, completely different output
Agent with no context
- Writes plausible code that ignores your conventions
- Invents endpoints that do not exist
- Guesses column names
- Creates a new helper when one already exists
- Confident, and wrong
Agent with your context
- Follows the patterns already in that project
- Uses endpoints from the real inventory
- Reads the actual schema and database logic inventory
- Finds and reuses the existing helper
- Behaves like an engineer who read the docs first
The gap between those two is not model capability. It is this stage. It is also why “production-ready” is achievable at all — a first draft that follows your conventions is close to mergeable; one that does not gets rejected on sight.
There is a second benefit with nothing to do with AI. This is the artefact set that makes the move from owners to stewards possible. Everything written here is just as useful to a new hire in week one.
1.1 — The Memory Structure
Plain Markdown in the repo, reviewed in PRs like code
What lives where, and which agents read it
Why Markdown in the repo, not a wiki or a vector DB
Three reasons. It is reviewable in a pull request, so the same process that keeps code honest keeps it honest. It versions with the code, so you can see what the architecture looked like at any past release. And it goes stale visibly — a stale doc in a diff gets noticed, a stale wiki page never does. A vector index gets added in Stage 5, on top of this, when volume needs it.
1.2 — The Patterns File
The difference between a draft your team merges and one they reject on sight
An agent that has not read your conventions writes correct, idiomatic code that looks nothing like the rest of the file. Reviewers reject it, correctly, and then conclude the tool does not work. So we capture what this codebase actually does — not what a style guide says it should.
| Area | What gets recorded | Why an agent needs it |
|---|---|---|
| Layering | Where logic belongs between API handler, service, repository and the database | Otherwise it puts business rules in an API handler and the reviewer sends it back |
| Error handling | Exceptions vs result types, what gets swallowed, what bubbles | Inconsistent error handling in a calculation engine is a real defect class |
| Logging | What gets logged, at what level, with what correlation id | Support cannot trace an alert without it |
| Validation | Where input is validated and how failures are surfaced | Duplicated or missing validation is a common review rejection |
| React conventions | Component structure, hooks, state management, routing, the existing data-refresh pattern | A screen that refreshes differently to every other panel is a defect |
| SQL conventions | Naming, parameterisation, how migrations are structured | Generated SQL that does not match makes the DBA review harder, not easier |
| Known anti-patterns | Things in the codebase that should not be copied | Agents imitate what they see. Some of what they see is old and wrong |
Where the codebase contradicts itself
It will, in places. Two modules do the same thing differently because they were written years apart. The patterns file has to pick a side and say so — otherwise every agent output starts an argument in review. Picking is a tech lead decision, made once, written down.
1.3 — The Domain Glossary
Business language to code, across every layer
Somebody says “add an alert when this value breaches its configured limit.” An agent needs to know exactly which backend services, which React components, which queries and which tables that means. Without the mapping it guesses. A wrong guess in critical business logic costs more than an agent that stops and asks. The rows below are illustrative; the real entries come from n.tasc’s own domain owners.
| Business term | Backend services | React UI | Data layer |
|---|---|---|---|
| Core calculation | CalculationService, CalculationEngine | <CalculationSummary /> | calculation inputs, result tables |
| Configured limit / threshold | ThresholdEvaluator | <LimitsPanel /> | threshold config rows |
| Upstream feed | FeedIngestionService | feed status indicator | feed staging tables |
| Scheduled job / batch | JobScheduler, BatchRunner | <JobMonitor /> | job history tables |
| Alert Rule | AlertRuleEvaluator, AlertDispatcher | <AlertsPanel />, useAlerts hook | rule definition tables, alert history |
| Report | ReportService | <ReportView />, report routes | reporting queries |
| Client Code / UCC | ClientResolver | <ClientSelector /> | client master (never in agent context) |
These names are illustrative
They show the shape of the artefact. The real glossary is generated by agents reading your actual code, then corrected by your engineers. It usually takes two or three passes before the team stops arguing with it. That argument is where the value is.
1.4 — Mining Your Own History
Your own history is the training data
Golden examples
- Five specs that were actually good to build from
- Five well-written bug reports with clean repro steps
- Three release packs a tester found useful
- Agents copy these, not a generic template
Defect patterns
- What has broken in n.tasc over the last year, by area
- Which recur — same bug class, new place
- Which were caught in review vs which escaped to UAT
- Sets the priority order for the Stage 2 test backfill
Regulatory history
- Past circulars and what each required in code
- How long each took from circular to UAT-ready
- Which modules regulatory change keeps landing on
- Trains the Regulatory Watch Agent on your real obligations
Review history
- What reviewers actually push back on, by frequency
- The comments that recur across many PRs
- Those become rules the Code Review Agent checks
- Turns tacit standards into enforced ones
Stage 1 deliverables
Populated .ai-memory/ · module docs reviewed by their current owners · patterns file with contradictions resolved · domain glossary reviewed by the Domain Owners · API and database logic inventory · golden examples · defect and review pattern analysis setting the Stage 2 priority order.