Take 5 developers. Put them on the same Git repo. Let them freely use Cursor, Copilot, or Cline without any shared rules. In a month, your architecture will have no soul left. Welcome to the Silent Divergence.
Generative AI, by definition, produces what it has seen most often across public GitHub repositories. For a technical team, the risk is massive: the total loss of your code's identity. If your studio's DNA (like ours at Vibrisse) is eco-design, hardcore accessibility, or squeezing 60fps out of React Three Fiber, a "vanilla" AI will suggest generic solutions — often bloated and over-engineered. It silently erases your team's expertise commit by commit, replacing it with invisible technical debt.
Code doesn't lie. Generic AI does.
The "Best Practices" War and the Illusion of Authority
Worse than the statistical average, I regularly observe what I call the LLM War. Developer A asks ChatGPT for a solution; it proposes Pattern X, swearing it's the state of the art. Developer B asks Copilot; it pushes Pattern Y as the absolute standard. Each developer merges their code with blind trust in "their" AI. The result? The team parasitizes itself, the architecture becomes schizophrenic, and PR debates drag on forever ("But Claude told me this was the best practice!").
The danger of AI is that it constantly navigates blind between three contradictory realities:
- Global "best practices" (theoretical state of the art, often over-engineered for your actual use case).
- The prompting developer's personal habits (AI adapts to their individual style to please them — pure sycophancy).
- Your project's actual reality (your specific architectural decisions, business constraints, or even the technical debt you've consciously accepted).
Left unconstrained, AI will naturally ignore reality #3 (which it knows nothing about) to enforce #1 or flatter #2.
The truth is, before writing a single line of code or firing a single prompt, your team must do what no AI will ever do for you: stop and document the reality of the project. That founding vision — your real best practices, your deliberate choices — must then be encoded to force your team's AIs to align with the codebase, not with their training statistics. That's the essence of Context-as-Code.
0. The Vision Before the First git init
This is the point nobody wants to hear because it can't be bought or installed. Before opening an IDE, before creating the repo, before even picking a framework: document the project's vision.
Not a Confluence page stuffed with UML diagrams nobody will read. A living, short, brutally honest document that answers three questions:
- What are our real constraints? (Budget, performance targets, GDPR, mandatory accessibility...)
- What are our deliberate choices and why? ("We don't use Redux because our state is simple and we value readability over theoretical scalability.")
- What is explicitly forbidden in this project, and why? ("Zero unaudited external dependencies. We're a team of 3 — we can't maintain everything.")
This document isn't just for humans. It's the founding brief for your AI. Without it, the agent fills the void with its training statistics. And those statistics are the average of GitHub — not your project.
AI amplifies what it finds. If it finds emptiness, it invents. If it finds a documented vision, it executes.
1. The Shared Project Prompt (The .cursorrules Myth)
Stop letting AI guess the repo's rules, or hoping every developer manually briefs their assistant at the start of each session. AI must become the team's unyielding guardian of consistency.
Today, everyone swears by the .cursorrules file. But nuance matters: this file is not magic and was never standardized. For a long time, it was a proprietary convention hardcoded by specific editors (Cursor, Cline, Windsurf).
The underlying architectural concept, however, has become universal. More robust standards have taken over — notably the .agents/ folder with local AGENTS.md files, popularized by autonomous agent SDKs like Antigravity (Google DeepMind). Whether you use your IDE's native mechanism or an agent orchestrator, the principle is the same: Context-as-Code. By versioning your rules at the project root, you enforce consistent AI behavior for every member of the team.
Here's a concrete example of what a shared context looks like in production:
# Project Rules
<stack>
React, TailwindCSS. No external component libraries. We build everything in-house to guarantee performance.
</stack>
<anti-boilerplate>
KISS principle is mandatory. AI naturally over-engineers to appear "Enterprise-ready". No preventive abstractions (empty interfaces, complex design patterns). Keep the code flat.
</anti-boilerplate>
<accessibility>
Every interactive element MUST have valid ARIA attributes. Non-negotiable.
</accessibility>
The Context "Time-Travel" (Versioning)
The biggest advantage of Context-as-Code is pure, hard versioning. Because your files live in Git, AI travels through time. You do a git checkout on a two-year-old branch to patch a v1? The agent reads the architectural rules of that era. It won't try to inject your shiny new v3 pattern into legacy code. AI bends to the temporal reality of the branch. And to handle the "update" aspect — maintaining and distributing these rules across multiple repos without friction — dedicated platforms like Context7 are now emerging to synchronize this knowledge at team scale.
The Junior Developer Mentor Effect
This context file has a fantastic side effect on technical management. A junior developer left alone with a generic AI will often copy-paste hallucinations without understanding them. Conversely, a junior working in an IDE constrained by a strict context file gets "corrected" in real time.
The AI stops churning out code by the kilometer; it explains why you must use a specific structure or naming convention in this precise project. The agent becomes a genuine onboarding vector, transmitting team culture without monopolizing senior developers' time.
2. The AI-Ready Codebase and "Gold Standards"
The other paradigm shift: technical documentation (your READMEs and Wikis) must change its target audience. You're no longer writing only for humans — you're writing so that AI can autonomously index and understand the context.
-
The
/docs/patternsfolder: Instead of explaining theory, provide perfect code examples ("Gold Standards"). AI learns far better by imitation (Few-Shot Prompting) than from long theoretical explanations. This is how you "fine-tune" the context without actually fine-tuning the model. -
Modular Skills: The monolithic 10,000-token system prompt that saturates memory (and your budget) is dead. In 2026, AI equips itself with targeted "Skills" (e.g.,
.agents/skills/a11y-debugging/SKILL.md). When you request an accessibility audit, the agent loads only that expert skill, applies it, then flushes its contextual memory. Software engineering principles applied to AI. -
Actionable Docs and the MCP Ecosystem: An AI-Ready Codebase goes beyond local Markdown files. AI must be able to answer "How do we usually handle fetch errors in this project?" by reading the living documentation. And today, thanks to the MCP (Model Context Protocol) standard, the agent can query the real world. Instead of letting AI hallucinate a design style or forcing a dev to hunt for hex codes, the agent can query a
@modelcontextprotocol/server-figmaserver to read design tokens directly from the source. Zero approximation. Zero copy-paste. Total control.
3. AI as "First-Responder" (Pre-Reviewer)
Finally, in a team context, AI isn't just an author — it's a critic. Think of it as eslint for your architecture. ESLint checks form — a missing semicolon, an unused variable. The AI Pre-Reviewer checks substance: does this component have a reason to exist? Does it duplicate something built yesterday by a colleague? Does it respect your business constraints? One level above. And like ESLint, it runs before code ever reaches a PR.
-
Pre-commit AI (LLMOps): Don't ask the LLM to be careful. Block execution. Local agents can validate that code respects your
AGENTS.mdbefore the commit is even sent. Here's a pragmaticpre-commithook using a local SLM (via Ollama) to review a diff with zero Cloud data leakage:
#!/bin/sh
# .git/hooks/pre-commit
DIFF=$(git diff --cached)
PROMPT="Analyze this diff against our AGENTS.md. Return only 'PASS' or 'FAIL: [Reason]'."
# Instant local execution (e.g., Microsoft Phi-3-mini-4k-instruct)
RESULT=$(ollama run phi3 "$PROMPT \n\n $DIFF")
if echo "$RESULT" | grep -q "^FAIL"; then
echo "🛑 Agent blocked the commit: $RESULT"
exit 1
fi
This local CI barrier prevents Silent Divergence from ever reaching the main branch.
- Semantic Consistency: The agent scans the repository to ensure a new component or service doesn't duplicate a function written yesterday by a colleague. Without global context, AI has a nasty habit of reinventing the wheel, generating invisible technical debt.
Conclusion: Craftsmanship in the Age of AI
A construction site without an architect's blueprint is a fast ruin. A project without a documented vision is a soulless codebase six months in — and AI will have accelerated the process faster than you ever imagined.
In a team, AI shouldn't be seen as a simple "code generator" or a productivity shortcut. It must be configured as an unyielding Pair Programmer that has internalized the team's culture, real constraints, and history. And for that, it needs you to first do the work it cannot do for you: think, decide, and write that founding vision.
Code doesn't lie. Generic AI does. The difference between the two is your AGENTS.md — your architectural .eslintrc, versioned, shared, and unyielding.
In your team, what's the reality? Documented vision before the first commit, or discovering the architecture as you go?
Proudly developed in Beauce, Québec 🇨🇦. Interested in the alliance between immersive web engineering and local AI sovereignty? Let's connect via Vibrisse Studio!
Top comments (0)