Office Hours — How do you keep AI coding agents aligned with your team's codebase standards, style guides, and architectural decisions?

How do you keep AI coding agents aligned with your team’s codebase standards, style guides, and architectural decisions?

The honest answer is you can’t fully automate this yet, but you can constrain the problem space ruthlessly.

Start with what agents can actually verify: linters, formatters, and type checkers. Feed these into the agent’s reward loop before it commits anything. If your codebase runs Black, ruff, and mypy on every PR, wire those into the agent’s feedback loop so it fails fast when it violates them. Same with your architectural guardrails, if they’re enforceable (no circular imports, no direct database access outside a specific layer).

Making Enforcement Actionable

The mechanical wins compound. If your CI gate runs five linters and a type checker, the agent sees immediate feedback on every generated chunk. This is cheap relative to the token cost of fixing style issues downstream. Claude Opus 4.7 can iterate through a full test-lint-type-check cycle in under a minute per module. Run that loop before the agent even opens a PR, and you’ve eliminated entire categories of review friction.

Consider a concrete setup: you have a FastAPI service with Pydantic models. Configure your agent to run this before any commit:

black . && ruff check --fix . && mypy . && pytest --cov

Claude Opus 4.7 or GPT-5.4 can parse the output, understand why the type checker failed, regenerate the problematic function, and re-run the suite in a single agentic loop. Three failures caught and fixed before a human even sees the code. The token cost per iteration is roughly $0.08 at current pricing. Compare that to a 20-minute code review to catch the same three issues.

The harder stuff, style guide enforcement, naming conventions, code organization philosophy, needs to live in the system prompt and context. Pull your CONTRIBUTING.md, architecture decision records, and recent merged PRs that exemplify good patterns in your codebase, then feed those as context before the agent touches anything. This is expensive in token consumption, but it’s cheaper than reviewing bad code. For a typical codebase, injecting 4-6 recent high-quality PRs plus architecture docs runs about 8-12K tokens per agent invocation. At current frontier model pricing, that’s roughly $0.12 per run on GPT-5.4. Compare that to 15 minutes of senior engineer review time, and the math is obvious.

Context Injection for Architectural Alignment

For architectural decisions specifically, make them queryable. If the agent needs to add a new module, embed a recent decision log or architecture diagram in context so it knows whether you’re doing event-driven systems or CQRS or layered monoliths. Claude Opus 4.7 and GPT-5.4 can reason over structured guidance, but they need it explicitly. A one-page ADR (Architecture Decision Record) in the prompt context can eliminate entire classes of wrong turns.

The tradeoff here is real. A 10K token context window on architectural context uses about 15% of a typical agent invocation budget, but it prevents the agent from making three wrong architectural turns that would require human correction. The agent won’t invent novel patterns. It will faithfully execute the patterns you’ve shown it.

Handling Subjective Judgment

Where agents still drift is on subjective calls: “Should this be a utility function or a class method?” or “Is this the right abstraction level?” These aren’t verifiable by a linter. They require judgment.

The critical insight here is that agents fail not because they’re stupid, but because there’s no fast objective signal. A test either passes or it doesn’t. A linter either fires or it doesn’t. But “is this a good abstraction?” has no automated answer. Agents trained to follow feedback loops optimize for what they can measure. When the measurement disappears, they drift.

Keep humans in the loop for review gates at these boundaries. Code agents are excellent at mechanical tasks: refactoring, adding tests, fixing linter errors, expanding existing patterns. They’re not yet trustworthy for architecture-level decisions without review.

Where Agents Still Drift

The real constraint is consistency over time. An agent working from your codebase context on day one will diverge by day fifty as it accumulates minor style choices that weren’t in the original context window. Document your conventions in executable form (linters, type checkers, auto-formatters) rather than prose guides. Agents follow rules. They infer conventions poorly.

If you have subjective style preferences not captured by your linter, consider making them capturable. If your team prefers builder patterns over long constructor chains, encode that as a custom linting rule or a template in your code examples. If you hate one-liners in conditional branches, enable that as a flake8 rule. The agent will follow.

Bottom line: Automate enforcement (linters, type checkers), embed style guide context aggressively in prompts, and keep humans reviewing anything touching architectural boundaries. Don’t expect agents to learn your team’s unwritten conventions. The agents working today are excellent at operating within constraints. They’re not excellent at inferring them.

Question via Hacker News