Encoding Team Standards
Rahul Garg · article · 2026-03-31 source ↗ Reader 🖥️
Agent SkillsAgent Context Files (CLAUDE.md / AGENTS.md)GuardrailsIntent DebtOrganizational Legibility
A team's standards for how AI should generate, refactor, secure, and review code must stop living as tacit judgment in senior engineers' heads or as unread documentation, and instead be encoded as small, versioned, repository-resident AI instructions — because an instruction's execution is its application, which turns consistent team judgment into a side effect of the normal workflow rather than a separate step that depends on someone remembering and applying it under pressure.
practical · argumentative — A practitioner essay (part of a martinfowler.com series on reducing AI-development friction) that diagnoses a specific failure mode and argues for one concrete fix, illustrated with anecdotes from the author's consulting practice and closed with explicit adoption/calibration guidance.
Structure
| Part | Role |
|---|---|
| Opening — the senior engineer's tacit, instinctive judgment as the team's most valuable and fragile asset | context / problem statement |
| The Consistency Problem — same codebase, same AI, materially different results depending on who prompts, because instructions (not AI knowledge) vary by person | diagnosis |
| Executable Governance — the two moves (tacit-to-explicit, documentation-to-execution) that convert standards into instructions whose execution is their application | core thesis |
| What This Looks Like — the four-element anatomy of a well-structured instruction (role, context requirements, categorized standards, output format) | mechanism / method |
| Surfacing the Tacit Knowledge — the extraction interview process and its side benefit of surfacing disagreement among seniors themselves | method / evidence |
| Where Standards Meet the Workflow — generation-time vs. review-time application and why earlier application has more leverage | elaboration |
| Standards as Shared Infrastructure — repository placement and PR review as what keeps instructions from becoming a 'documentation graveyard' | mechanism / durability argument |
| Calibration — team-size heuristic and adoption sequencing; honest costs | scope-limiting / practical guidance |
Key terms
- Executable governance
Standards encoded as AI instructions whose execution constitutes their application — governance that happens as a side effect of the normal workflow rather than a separate, discipline-dependent step. - The Consistency Problem
Two developers on the same team, using the same AI tool, same codebase, and same project context, producing materially different results — not because the AI's knowledge differs, but because the instructions given to it differ by person. - Four-element instruction anatomy (role definition, context requirements, categorized standards, output format)
A specific, recurring structure the author claims any well-built executable instruction should have, regardless of its purpose (generation, refactoring, security, review) — categorized standards in particular encode the team's priority judgment (must/should/nice-to-have or critical/important/advisory), not just a flat list of knowledge.
Propositions
- explicitWhen AI-assisted development quality depends on who is prompting, senior engineers become bottlenecks — not because they write the code, but because they alone know what to ask the AI for — and this is a systems problem requiring a systems solution, not a skills problem that training, documentation, or more pairing can fix, because those approaches are slow and do not scale.conf: highrefinesHow to Turn Individual Talent into Organizational Excellence · p4 — Where that source frames team standards as enforced socially (peer accountability, shared language, psychological safety), this article proposes an executable, infrastructural mechanism as a complement — converting some of that social enforcement load into versioned, reviewed artifacts.
- explicit⚡ disputed & corroboratedTeam standards should be encoded as versioned, repository-resident AI instructions rather than wiki documentation or tribal knowledge, because an instruction's execution is its application — it does not depend on a developer remembering and applying it under time pressure — which makes governance a side effect of the normal workflow rather than a separate disciplined step.conf: highsupportsThe Intent Debt · p8 — Both diagnose the same root failure: agents (and, here, differently-experienced developers) carry forward no tacit intent unless it is externalized into a readable, structured artifact — this article proposes one concrete executable format for that externalization.supportsThe Intent Debt · p25 — This article's categorized, repository-resident instructions are a specific instantiation of the substrate Osmani names (AGENTS.md, ADRs, learnings files, specs) for externalized intent — adding a concrete four-part anatomy to that general claim.contradictsAudit your Agent files · p4 — Complicates this article's optimism that encoding a standard as an executable instruction guarantees consistent application: across 288 runs on 17 real tasks, context files (AGENTS.md/CLAUDE.md) did not produce a clear correctness gain, suggesting 'executable' does not by itself guarantee 'reliably executed.'supports ←The AI-Native SDLC playbook · p7 — Both independently converge on the same practice: team standards belong as versioned, repository-resident, agent-readable files rather than wiki documentation or tribal knowledge, maintained and reviewed like code.refines ←John Cutler's Post · p4 — Encoding-team-standards' proposal — versioned, repository-resident AI instructions that every developer's AI session draws on — is a clean real-world instance of 'shared-context solo' infrastructure. Cutler's framing doesn't contradict it (it never claims to deliver multiplayer collaboration) but situates it precisely: valuable foundation, not the destination, and distinct from the shared-reasoning problem multiplayer solves.supports ←Coding Agent Development Workflows · p5 — Both independently converge on the same fix: team conventions must be encoded as versioned, repository-resident artifacts that execute (or are directly referenced) rather than living as separate wiki documentation per tool.
- explicitA well-structured executable instruction has four distinct elements regardless of its purpose — role definition (sets the expertise/perspective lens), context requirements (explicit dependencies), categorized standards (a priority structure like must/should/nice-to-have or critical/important/advisory that encodes the team's judgment, not just its knowledge), and output format (ensures comparability across runs and developers).conf: highsupportsFrom AI Code to Trusted Software: Harness Engineering in Practice · p17 — Both independently converge on compressing organizational AI governance into a small number of categorized elements (this article's role/context/categorized-standards/output-format vs. the other source's Purpose/Articles/Allowances framework) rather than a flat rulebook.
- explicitThe process of extracting these instructions through structured interviews with senior engineers has value beyond the resulting artifact — it surfaces previously unarticulated disagreements among the seniors themselves, as when two senior engineers were found to have silently held different thresholds for a 'critical' versus 'important' security concern, a disagreement that had never surfaced because each reviewed different pull requests.conf: high
- explicitEncoded instructions do not make a less experienced developer more experienced; they make their inexperience less costly — illustrated by a junior developer's first use of a review instruction flagging a missing authorization check that previously was only caught when a senior happened to be the reviewer.conf: high
- explicitcorroboratedWhere in the development workflow a standard is applied changes its value: generation-time application has the most leverage because it prevents misalignment before it happens, while review-time application is the last opportunity to catch misalignment — so the earlier standards are applied in the workflow, the fewer issues reach review.conf: highsupports ←Coding Agent Development Workflows · p6 — Tune's practice of pushing every manual catch upstream into a linting rule or convention doc is a concrete instance of the claim that generation-time application of a standard has the most leverage, because it prevents the issue before it occurs rather than catching it at review time.
- explicitdevelopedThis approach is scale-calibrated, not universal: the signal that a team needs it is whether AI-output quality visibly varies by who is prompting, or whether generation/review work routes through a handful of people who know how to prompt effectively; small teams (around five people) may not need it, while teams of around fifteen almost certainly do, and the right adoption sequence is one instruction first (usually generation or review), with further instructions following adoption rather than preceding it.conf: highextends ←Coding Agent Development Workflows · p10 — Tune's principles-driven org-vs-team resolution gives a concrete answer to exactly the calibration question the other article leaves open — at what level and under what signal a team should adopt this degree of explicit standardization.
- explicitThese instructions avoid becoming an abandoned 'documentation graveyard' specifically because of where they live and how they're maintained: repository placement makes drift visible in the normal course of work — appearing in diffs, referenced in PR templates — rather than requiring a deliberate audit, so the standards evolve through the same pull-request workflow the team already uses for code.conf: high
Arguments
The AI-output consistency problem is a systems problem requiring a systems solution (executable instructions), not a skills problem solvable by training, documentation, or pairing. strength: high
Explicit premises:
- Training juniors, writing better documentation, and more pairing 'all help, but they are slow and they do not scale.'
- The relevant knowledge already exists on the team — it simply has no vehicle for consistent distribution.
Implicit premises:
- Scaling consistent judgment across a growing team requires decoupling the judgment from any single person's memory and attention.
- Any mechanism that still depends on a human remembering and applying a standard under time pressure (checklists, wikis) will fail the same way prior codification efforts have — 'that gap is where most codification efforts quietly fail.'
Inferences:
- Only a mechanism whose execution IS the application — an instruction the AI runs — can close the documentation-to-practice gap that doomed prior codification attempts.
- This implies skills-based interventions are not wrong, just insufficient on their own — they remain necessary for judgment calls that cannot be codified, but cannot by themselves solve the scaling problem.
Instruction-writing effort should be weighted toward earlier points in the workflow (generation, refactoring) rather than concentrated only at review-time, because the same team judgment applied earlier produces fewer downstream issues than the identical judgment applied only at the end. strength: medium
Explicit premises:
- Generation-time instructions 'prevent misalignment rather than catching it after the fact.'
- 'Review-time is the last opportunity to catch misalignment.'
Implicit premises:
- Misalignment caught later costs more (rework, additional review cycles) than the same misalignment prevented earlier.
- Applying judgment earlier does not simply relocate the same amount of friction to an earlier stage, but strictly reduces total friction.
Inferences:
- A team with the capacity to build only one instruction should generally prefer a generation or review instruction over a narrower refactoring-only instruction — matching the article's own explicit calibration advice.
- This creates an implicit priority ordering (generation > refactoring/security > review > CI) for where to invest first, though the article does not state this ordering directly.
Narratives
- On one project, the process of extracting a shared security instruction revealed that two senior engineers had quietly held different thresholds for what counted as a 'critical' versus 'important' security concern — a disagreement that had never surfaced because each had been reviewing different pull requests.
→ Supports the proposition that the extraction/interview process has value independent of the resulting artifact — it forces previously tacit, unexamined disagreement between senior engineers into the open. - After a resulting review instruction was adopted, a less experienced developer's first use of it flagged a missing authorization check on a newly added endpoint — exactly the kind of issue that had previously only been caught when a senior happened to be the reviewer.
→ Supports the proposition that these instructions make inexperience less costly rather than making the developer more experienced — illustrating the mechanism's practical payoff concretely rather than abstractly.
Questions addressed
- ✅ Why does the same AI, on the same codebase with the same project context, produce materially different results for different developers?
Because the instructions given to the AI (what to generate, check, flag, reject) vary by person, not because the AI's knowledge of the project varies. - ✅ Is this consistency problem best solved by more training, pairing, or documentation?
No — explicitly argued to be insufficient because these approaches are slow and do not scale; a systems solution (executable instructions) is proposed instead. - ✅ Does every team need this?
No — explicitly scale-calibrated via a heuristic (visible output-quality variance, or work routing through a few people who know how to prompt); 'teams of five may not need this, teams of fifteen almost certainly do.' - ✅ How do teams keep these instructions from becoming unmaintained, abandoned documentation?
Repository placement plus the normal pull-request review workflow make drift visible in the ordinary course of work, without requiring a dedicated audit. - ⭕ Does the AI reliably execute a categorized-priority instruction as written, every time, under every context load?
Gaps
- incompleteThe article assumes that once a team standard is encoded as an executable instruction, the AI reliably executes it as written. It never engages instruction-following limits — an instruction competing for context/instruction budget against other project priming documents, or an AI silently failing to apply a 'categorized standard' under pressure — that this corpus's own AGENTS.md-bloat and context-budget literature treats as a real, measured failure mode.
Read next: AGENTS.md/CLAUDE.md instruction-budget and bloat literature (e.g. studies measuring whether context files produce a measurable correctness gain) to test whether 'executable' instructions are reliably executed at scale, or degrade the same way bloated context files do.closed byStop Using /init for AGENTS.md — Supplies exactly the measured instruction-budget/bloat evidence that gap called for: two 2026 studies quantify how AGENTS.md content competes for context/instruction budget and silently degrades (cost +20%+, success -2-3% for auto-generated/redundant content), confirming that 'encoding a standard as an executable instruction' is not reliably executed at scale once the file grows — it degrades the same way bloated context files do. - incompleteNo discussion of what happens when instructions conflict with each other (e.g., a generation instruction's architectural-compliance requirement versus a refactoring instruction's 'avoid premature abstraction' guidance), or at what point a growing library of small, single-purpose instructions itself becomes a new coordination and maintenance burden analogous to the 'documentation graveyard' problem the article claims repository placement solves.
Read next: Look for guidance or case studies on managing a growing library of composable AI instructions/skills at scale — conflict resolution, deprecation, and ownership once dozens of small instructions exist rather than one or two.closed byCoding Agent Development Workflows — Tune's single-source-of-truth fix (pointing every agent's and tool's own config, including a third-party tool like CodeRabbit, at the same shared convention/ADR files) directly resolves the 'instructions conflicting across tools' half of this gap with a concrete, working mechanism — though it does not address the gap's other half, the self-conflict risk as a library of many small instructions grows. - incompleteThe two central anecdotes (two seniors with different severity thresholds; a junior catching a missing auth check) are both single, author-reported incidents from the author's own consulting practice. No measurement is offered of defect rates, review-quality variance, or time-to-competency before versus after adopting these instructions across a real team over time.
Read next: Look for quantitative studies measuring review-outcome or defect-rate variance across developers before and after adopting shared, versioned AI instructions, rather than anecdotal before/after accounts.
Closes gaps elsewhere
- The Agentic P&L: Beyond the Empire of Headcount · g5 — Gives one concrete, demonstrated method for the tacit-to-explicit conversion that gap found merely assumed: structured interviews with senior engineers, organized around pointed questions (what triggers rejection, what's checked instinctively, what separates clean from over-engineered refactoring), whose answers map directly onto instruction structures — with a documented case where the interview process itself surfaced a previously invisible disagreement between two seniors. Still single-practitioner, anecdotal evidence rather than the systematic knowledge-management literature that gap called for, so it narrows rather than fully closes the gap.
- How Fast-Growing Companies Can Make Better Decisions · g5 — Offers a working counter-case to the bare assumption that gap flagged: this article shows tacit judgment partially captured and made explicit through a specific interview-to-instruction pipeline, with a concrete before/after example (a junior catching a missing authorization check). It doesn't address whether the resulting codified standard transfers across different contexts/teams, which is the deeper transferability question the gap raises, so it narrows the gap for within-team codification specifically rather than closing the cross-context transfer question.
Related documents
- How to Turn Individual Talent into Organizational Excellence
- From AI Code to Trusted Software: Harness Engineering in Practice
- Charlie Hills 🦩's Post
- Stop Using /init for AGENTS.md
- Agent Skills: Google-Backed AI Coding Agent Workflow
- Alex Wang's Post
- Anatomy of a perfect Openclaw setup
- Audit your Agent files
- How Claude Code works in large codebases: Best practices and where to start
- Achieving Compliance as a Platform Engineering Team by Helping Developers