惯性聚合 高效追踪和阅读你感兴趣的博客、新闻、科技资讯
阅读原文 在惯性聚合中打开

推荐订阅源

The GitHub Blog
The GitHub Blog
A
About on SuperTechFans
The Cloudflare Blog
G
Google Developers Blog
博客园_首页
Martin Fowler
Martin Fowler
Apple Machine Learning Research
Apple Machine Learning Research
L
LangChain Blog
D
Docker
C
Check Point Blog
T
Tailwind CSS Blog
博客园 - 司徒正美
奇客Solidot–传递最新科技情报
奇客Solidot–传递最新科技情报
Hugging Face - Blog
Hugging Face - Blog
Microsoft Security Blog
Microsoft Security Blog
V
V2EX
博客园 - 叶小钗
T
The Blog of Author Tim Ferriss
酷 壳 – CoolShell
酷 壳 – CoolShell
IT之家
IT之家
M
MIT News - Artificial intelligence
Microsoft Azure Blog
Microsoft Azure Blog
博客园 - 【当耐特】
GbyAI
GbyAI

DEV Community

Authentication Security Deep Dive: From Brute Force to Salted Hashing (With Java Examples) Why AI Systems Don’t Fail — They Drift Spilling beans for how i learn for exam😁"Reinforcement Learning Cheat Sheet" I Replaced Chrome with Safari for AI Browser Automation. Here's What Broke (and What Finally Worked) How Python Borrows Other People's Work The $40 Architecture: Processing 1 Billion API Requests with 99.99% Uptime Vibe Coding: A Workflow Guide (From Zero to SaaS) Most webhook security guides protect the wrong side. The scary part is delivery. Headless CMS for TanStack Start: Build a Blog with Cosmic EU Age Verification App "Hacked in 2 Minutes" — What Actually Happened Comfy Cloud’s delete function does not actually remove files Running AI Models on GPU Cloud Servers: A Beginner Guide Event-driven media intelligence with AWS Step Functions and Bedrock I scored 500 AI prompts across 8 quality dimensions — here's what broke How to Call Google Gemini API from Next.js (Free Tier, No Backend Needed) The Portal Protocol: Reclaiming Human Connection in the Age of AI How to Fix Your Team's Scattered Knowledge Problem With a Self-Hosted Forum Intro to tc Cloud Functors: A Graph-First Mental Model for the Modern Cloud Designing Multi-Tenant Backends With Both Ownership and Team Access I Built a Neumorphic CSS Library with 77+ Components — Here's What I Learned PostgreSQL Performance Optimization: Why Connection Pooling Is Critical at Scale Cómo construí un SaaS multi-rubro para gestionar expensas en Argentina con FastAPI + Vue 3 🚀 I Built an Ethical Hacking Scanner Tool – Open Source Project I Replaced /usage and /context in Claude Code With a Single Statusline A Pythonic Way to Handle Emails (IMAP/SMTP) with Auto-Discovery and AI-Ready Design I Collected 8.9 Million Polymarket Price Points — Here's What I Found About How Markets Really Move EcoTrack AI — Carbon Footprint Tracker & Dashboard Everyone's Using AI. No One Agrees How. 5 self-hosted ebook managers worth trying in 2026 Building Your First AI Agent with LangChain: From Chatbot to Autonomous Assistant
Building ARCHITECTURE.md Files That Prevent AI From Makin...
Jai kora · 2026-05-16 · via DEV Community

Building ARCHITECTURE.md Files That Prevent AI From Making Silent Architectural Decisions

A few weeks into our experiment with an AI coding assistant, I noticed something odd. Variable names were shifting. Not dramatically. A rename here, a slightly reworded method there. Each change seemed reasonable in isolation. Professional, even.

But collectively, they were rewriting our architecture one rename at a time.

The Silent Coup

It started innocuously. The assistant would suggest replacing a small, plainly named method with a longer, more "enterprise" sounding one. The PR looked fine. More descriptive, right? Then it began restructuring how we organized service classes, introducing new abstraction layers that felt Enterprise Java-ish. Again, each individual change passed code review because none were objectively wrong.

Our human reviewers saw isolated improvements. Our automated reviewer, another AI, rubber-stamped the changes because they followed general best practices. No linter flags a variable rename. No formatter catches architectural drift.

A few weeks later, our codebase felt foreign. The naming conventions had subtly shifted toward verbose enterprise patterns. Service boundaries had blurred as the assistant introduced "helper managers" and "utility coordinators." The original lean architecture was drowning in abstraction.

The honest truth hit during standup when someone asked: "Why does this keep coming up?" We had spent half our sprint discussions untangling unnecessarily complex class hierarchies that had not existed a month prior.

Why Traditional Safeguards Failed

This was not a tooling problem. Our static analysis caught syntax violations perfectly. Our formatters maintained consistent indentation. Linters enforced style rules religiously.

But architectural decisions live in the spaces between the rules. When the assistant chose composition over inheritance, or decided to extract a new service class, or renamed methods to follow different conventions, these choices were invisible to mechanical constraints.

Human reviewers failed too, and for understandable reasons. Who flags a PR that renames a couple of variables and extracts a helper method? The changes looked professional. They followed general principles we had all learned in computer science classes.

The AI reviewer was even worse. It enthusiastically approved changes that made the code "more maintainable" according to whatever training data informed its judgment. Two AIs agreeing does not create architectural coherence. It creates compounded drift.

What Actually Worked

I started keeping an ARCHITECTURE.md file. Not as punishment for the assistant, but as explicit guidance about our actual architectural decisions and why we made them.

The file documents our naming conventions, why we keep service classes thin, and why we avoid deep inheritance hierarchies. More importantly, it explains the reasoning behind these choices: performance characteristics, team preferences, and integration constraints.

Every time the assistant made a questionable architectural call, I updated the document. When it introduced unnecessary abstraction layers, I added a section explaining our preference for composition patterns. When it renamed methods to be more "descriptive," I clarified our naming philosophy and provided examples.

This created a feedback loop that actually worked. The assistant began suggesting changes that aligned with our documented architecture. Not because it suddenly understood our preferences, but because the context was explicit rather than implied.

The Documentation Defense

The ARCHITECTURE.md file serves as a kind of architectural constitution, a set of principles that constrain both human and AI decision-making. It is not comprehensive documentation of every class and method. It is the theory of the system: how business problems map to code structure, what rules must always hold, and why certain patterns are preferred over alternatives.

I organize it around decision rationale rather than implementation details. Instead of documenting what the code does, it explains why it is structured that way. This gives both humans and AI agents the context needed to make consistent architectural choices.

The file evolves with the system. When we change architectural direction, we update the documentation. When AI agents make questionable choices, we refine the guidance. It is a living document that captures institutional knowledge about how we build software.

The Uncomfortable Reality

AI coding assistants are exceptionally good at writing code that works. They are terrible at understanding why your architecture exists and what constraints shaped its evolution. Without explicit guidance, they will optimize for whatever patterns dominated their training data, usually enterprise Java or academic computer science examples.

This is not the assistant's fault. It is doing exactly what we asked: writing better code according to general principles. The problem is that "better" is contextual, and context lives in documentation that most teams never write.

The ARCHITECTURE.md approach is not elegant or automated. It requires discipline to maintain and vigilance to enforce. But it is the only method I have found that consistently prevents AI agents from silently rewriting your architectural decisions.

Because the alternative, discovering weeks later that your codebase has quietly become someone else's idea of good architecture, is far worse than the effort of writing it down.