Inside T3 Code: 7 Engineering Practices Worth Stealing From an Agent-First Codebase
文章目录
Most developers are still learning how to get AI agents to write decent code.
T3 Code is further along. It’s an open-source control surface for coding agents, built by @theo and his team. A large share of the contributions to the repository come from T3 Code itself, often driven remotely. They’re building the tool that controls agents while using that same tool to change its own codebase.
That setup creates real constraints. An agent can kill the process it’s running inside, write to the live database, or make a change that works in one client and silently fails in the others. The repo has concrete engineering practices to keep that from happening. Here are seven of them worth stealing.
1. Write instructions around the damage an agent can cause
Most AGENTS.md files stay vague. Follow the style. Write tests. Don’t add random dependencies.
T3 Code’s file has a section called “The three ways to hurt yourself.” It names operations that are especially dangerous because the agent may be running inside the app it’s modifying:
-
Never kill processes by pattern (pkill -f). Capture and terminate the specific PID instead.
-
Never write to the live installation at ~/.t3/userdata.
-
Never hardcode origins such as VITE_HTTP_URL.
A bad process kill can take down both the app and the agent. Writing to the live data directory or baking in localhost origins creates silent breakage for remote clients.
A companion section called “Hit every surface” forces the agent to state which of these apply to the change: entry points, web/desktop/mobile clients, providers, agents and MCP, contracts, reverse states, connection modes, and documentation.
Steal this: Name the dangerous operations, explain how they fail, give the safe alternative, and make the agent explicitly list every surface the change touches.
2. Turn repeated instructions into executable rules
Agents can read a convention and still ignore it. T3 Code reduces that gap with a custom Oxlint plugin (oxlint-plugin-t3code) that contains roughly 40 rules. These enforce things that would otherwise live only in documentation: no polling loops or wall-clock time in tests, required reasons for suppressions, and blocks on certain RPC permission bypasses.
Steal this: If you leave the same review comment twice, turn it into a deterministic check. Move conventions out of prose and into tooling the agent cannot quietly skip.
3. Treat agent context as a limited engineering resource
People talk a lot about context window size. They talk less about context quality and growth. Every extra instruction, tool description, and document competes for the model’s attention.
T3 Code measures this. A CI workflow tracks the size of Claude’s system append, Codex’s additional context, and the MCP tool list. If a pull request increases the budget beyond the baseline, it needs an explicit agent-context-increase label. More context is not automatically better.
Steal this: Measure your instruction files and tool descriptions. Track changes in CI so growth stays intentional instead of silent.
4. Make local checks and CI use the same logic
A common failure: the agent runs a few checks locally, pushes, and CI fails on something it never saw.
T3 Code uses one shared change-mapping script (ci-changes.cjs) for both the local check:changed command and CI. Both decide which checks must run based on the files that actually changed. Agents are told not to run the full test suite; CI owns that. The feedback loop stays fast without two systems that can drift apart.
Steal this: Build one script that maps changed files to required checks and reuse it locally and in CI.
5. Treat prompts and tool descriptions like code
Application code, APIs, and queries get tests. The instructions that shape agent behavior usually don’t.
T3 Code has an evals/ directory for model-facing behavior covering MCP tool usage, thread titles, PR content, voice cleanup, and test signal quality. When a model-behavior bug appears, they add an evaluation case that fails before the fix and passes after it. Prompt or tool-description changes can then be checked against previously observed failures.
Steal this: Pick one critical agent workflow and build a small evaluation set around it. Every time the agent makes a mistake, add a regression case. Prompts are part of the software.
6. Let CI enforce policy, not review bots
The repo uses multiple automated reviewers (Macroscope, CodeRabbit, Codex, and custom agents), but the separation is clear: bots provide signals, CI is the merge gate. Passing CI is required. Automated review findings are not merge authorization.
Each custom review agent has a narrow job (effect-service conventions, test-signal quality, UI consistency, and so on). The test-signal agent is constrained against asking for more coverage. It can only suggest fewer or smaller tests. When an agent receives findings, it must verify them against the source, fix real issues, and document why false positives were dismissed.
Steal this: Give each review agent one narrow responsibility. Keep CI as the deterministic gate. Require verification of findings instead of treating the bots as authority.
7. Give agents real references, but isolate the data
Agents often invent plausible but outdated library usage. T3 Code keeps read-only copies of external repository documentation in a .repos/ directory so agents can consult the actual current docs (for example, Effect) instead of relying only on training data.
For test data, worktree setup scripts copy real data into an isolated environment. The rule is explicit: copy in, never symlink. Secrets and scheduled tasks are stripped. Data flows one way into the sandbox. A symlink would give the agent access outside its intended boundary. A copy gives realistic data without exposing the live environment.
Steal this: Keep version-accurate library references available to agents. Use isolated copies of real test data, remove secrets, and never give agents unnecessary access to the live environment.
The bigger lesson
These practices point to a different way of building software with agents. The shift is from “developers using AI as a coding assistant” to “developers designing environments where agents can make changes independently.”
That changes what good engineering looks like. The repository must communicate constraints clearly. Tooling must enforce them. Tests must catch behavioral regressions. CI must verify independently. The environment must limit the damage an agent can cause.
The goal is not an agent that never makes mistakes. It is an engineering environment where mistakes are cheap, detectable, and recoverable.
What I’d implement this week
Start with the things that limit damage, then add measurement and feedback loops:
-
Write three explicit NEVER rules for dangerous operations, with failure modes and safe alternatives.
-
Add a checklist that forces agents to identify every affected application surface.
-
Isolate agent workspaces from production data and secrets (copy, never symlink).
-
Turn the most repeated code-review comments into lint rules.
-
Make local validation and CI share the same change-mapping logic.
-
Track agent context growth in CI so expansion is intentional.
-
Add regression evaluations for your most important agent workflows.
The biggest risk with agents isn’t bad code. It’s an environment that lets bad code become expensive.
Which of these seven practices would reduce the most damage in your setup right now? Or what’s one constraint you’ve added that isn’t on this list?
Reply with it. The best ones will get pulled into a follow-up.



