Give Your AI Assistant a Map, Not a Flashlight

Point a coding agent at an unfamiliar repository and watch what it does: it greps. It opens files, reads a bit, opens more files, and slowly builds a partial mental model out of fragments — burning context the whole way and finishing with a picture that is mostly right and confidently wrong in a few places.

Then it writes a UserService. You already had one. It was called Member.

This is the central failure mode of AI-assisted development on a real codebase, and it is not a model capability problem. It is an information problem. The agent reinvented your primitive because nothing told it the primitive existed. Tiknix's answer is to make the codebase able to describe itself, and to hand that description to the agent before it writes anything.

Four tools, one job

Tiknix exposes structural introspection over MCP (Model Context Protocol), so any agent working in an instance can call them:

The critical design choice: these return pointers, not file bodies. The digest is token-bounded. An agent gets a complete structural picture for the cost of one modest tool call, then reads the two or three files that actually matter. Compare that with grepping its way to the same understanding across thirty file reads, arriving with a full context window and a partial map.

Why this works better than "read the codebase"

Three reasons, in order of importance.

1. It is complete

A grep finds what you searched for. The digest enumerates what exists. An agent that greps for "auth" finds the auth controller and concludes it has the picture; it does not know about TwoFactorAuth, PermissionCache, OAuthStateService, or the authcontrol wildcards, because it did not know to look. Completeness is the thing search cannot give you.

2. It is deterministic

The digest is generated by reading the code, not by summarizing it. Run it twice, get the same answer. Run it after a change, get the change. There is no drift between the map and the territory because the map is derived from the territory on every call — which is exactly what a hand-maintained ARCHITECTURE.md cannot promise.

3. It is structured for the decision the agent has to make

reuse_digest is not a generic dump. It surfaces precisely the fields that answer "does something already do this?" — controller names with permission levels, models with columns, services with method names. That is the shape of the question, so that is the shape of the answer.

The discipline that goes with it

The tools alone are not enough. Tiknix pairs them with a rule in its project standards that every agent working in the codebase reads:

Before creating any controller, model, or lib service, call reuse_digest and match the need against what already exists. For each capability, decide explicitly: REUSE an existing primitive, EXTEND one, or NEW — and if new, say why.

Forcing an explicit classification is the mechanism. An agent that must write down "REUSE lib/Mailer" cannot drift into writing its own SMTP wrapper; it has already committed to an answer. And in the plan pipeline the decision is recorded structurally — each subtask carries a reuses field listing what it builds on, which the executor expands into exact routes, columns, and method names in the worker's brief.

The standards go further and call the failure by name:

A new controller/model/service when a close match already exists is a defect — prefer a method on an existing controller and a column on an existing model.

Not a style preference. A defect. That framing matters, because reinvention does not look like a bug in review — the new code works, the tests pass, and nothing is obviously wrong. It only shows up six months later as two overlapping user models that disagree about who is active.

Validation as a second layer

Structural knowledge prevents architectural mistakes. Convention mistakes need a different tool, so Tiknix also exposes validators — validate_php, check_redbean, check_flightphp, and a full-validation pass — plus a hook at .claude/hooks/validate-tiknix-php.py that runs on edits and blocks invalid bean type names outright.

The layering is deliberate. Introspection prevents "you built the wrong thing." Validation prevents "you built it the wrong way." Both operate before the code lands, which is when correction is cheap.

The principle, stated generally

Even outside Tiknix, the pattern is worth stealing: if you want an agent to reuse your primitives, make your primitives enumerable.

That can be an MCP server, a generated inventory file, a make manifest target, or a README section you actually keep current. The mechanism matters less than the property: at the moment the agent decides what to build, a complete and accurate list of what already exists should be one cheap call away. Without that, every session starts from zero and reinvention is the rational default.