Teaching Agents Your Platform
This is the technical track that runs in parallel with the people work. The two depend on each other. A coaching session on a codebase the agent can’t reason about produces frustration. A well-prepared codebase with no engineers willing to use it produces nothing.
The work goes by several names: agent enablement, platform readiness, context engineering. The shape is consistent. You’re teaching agents your platform so they can be effective on the code your business actually runs on.
The greenfield trap
Most demos of agentic coding happen on fresh repositories. Someone types a one-shot prompt. An app appears. The video gets shared. Everyone is impressed.
Your codebase is not that codebase. Yours has years of accumulated convention, multiple frameworks layered on each other, half-deprecated patterns nobody’s removed, and tribal knowledge that lives in people’s heads and old chat threads. An agent looking cold at your codebase will produce code that compiles, that solves the problem in a vacuum, and that violates a half-dozen unwritten patterns the team has been carrying for years.
The team will conclude, reasonably, that the tools don’t work on real code. The work of building the bridge between agent and codebase is what this chapter is about.
Watch out → When external companies ask about our transformation, our focus on existing codebases is what resonates the most. Greenfield agentic coding is the easy case. Real value lives in making agents productive on the code your business already runs on.
What teaching the agent your platform means
You’re giving the agent the kind of context a new senior engineer would need to be effective. Not a syntax reference. The patterns, conventions, and decisions an experienced person on your team would explain in their first week:
- Frameworks and component patterns. What UI library, what conventions, what backend service patterns are standard, what’s the routing model, the state management, the auth flow.
- Integration patterns. How services talk to each other. Where API boundaries live. The contract between frontend and backend.
- Tooling and testing expectations. What runs in CI. What test patterns are required. What “ready to merge” actually means.
- What’s deprecated. This matters more than people realize. Codebases accumulate old patterns alongside new ones. An agent that sees both will sometimes choose the wrong one. Tell it which is which.
The agent uses this context to produce code that fits your codebase rather than fighting it.
In practice, this context starts as something developers create on the fly during agent sessions. They explain a pattern, the agent uses it. Nothing is captured anywhere yet; it’s all in the moment of the session. The work over time is to migrate that context into shared resources everyone can leverage, so the next developer doesn’t have to discover the same thing the next time. The transition from “developer in the room with the agent” to “knowledge available to all agents in all sessions” is what scales the investment.
Developer steering → The inventory will feel infinite. Don’t try to document everything at once. Start with the patterns coming up most often in agent sessions where the agent is producing wrong-shaped code. Each fix becomes a new piece of context. Over time the document set covers what matters.
The bidirectional model
Treat the knowledge base as a living system, not a static resource.
Agents read your patterns when they work on your code. That’s the baseline. But sessions also surface gaps. Patterns that aren’t documented, edge cases that produced unexpected behavior, conventions that matter but aren’t written down. The developer notices it during the session, corrects the agent, explains the missing context, and asks the agent to capture it as a documentation update.
The proposed update goes through review like any other contribution. Some get merged. Some get rejected. Some get edited. The knowledge base grows from real working sessions rather than from a documentation project.
Two things this gives you. The documentation stays close to reality, because it comes out of real work. And the agents you have now help build the context that makes the agents you’ll have next year more effective.
Local-first workflows
When an agent can write code and run it locally — execute the test, see the output, react to the failure — the feedback loop tightens dramatically. The agent verifies what works in seconds. It can catch its own mistakes. It produces better code with less back-and-forth.
When the workflow requires pushing code to a remote environment to validate every change, the loop stretches to minutes or hours. Iteration slows. The cumulative effect over a long session is large.
Investing in local executability — branches that can be tested without long deploy chains, local test runners that match CI, environments that come up fast — pays back twice. Agents work better in tight feedback loops; developers do too. Sell it as a developer experience investment that happens to also unlock agent productivity.
Stalled → If your developers were already frustrated with slow feedback loops before agents arrived, agentic transformation will amplify that frustration. Agents can’t recover wins that developer experience is bleeding away. DX investment is one of the highest-leverage things you can do.
Watch out → Coaching sessions and hackathons can get hijacked by environment friction. One team came into a session planning to build a feature and spent most of the time fighting deployment infrastructure. The agent had working code in under an hour; the environment couldn’t accept it at that speed. The session turned into an infrastructure debugging exercise.
The technology will keep changing — the work won’t
Right now, the ways to give agents context are evolving fast. We’ve used several approaches:
- Direct context injection. Files and folders pasted into prompts.
- Repository-resident files. Markdown documents at the root of each repo that get included automatically in agent context.
- Knowledge bases as MCP tools. Structured collections of documents the agent can search, read, and contribute back to.
- Skills. Combinations of markdown, scripts, and CLI tools that bundle a capability the agent can invoke.
Six months from now there will be more options than there are today. Trying to pick the right one is mostly a distraction.
What’s important is the content of the context. Inventorying your frameworks. Writing down your conventions. Documenting decisions and why. Capturing what experienced engineers know but isn’t written anywhere. None of that becomes obsolete when the delivery mechanism changes.
What you’re building, across all of this, is a system where agents are first-class participants in your platform, with access to the same knowledge experienced engineers have, the same tooling, and increasingly the same ability to contribute to both. Some teams call this the agent-legible environment. Investment in legibility is what turns the cultural moment into sustained momentum.