Why CLAUDE.md Is Not Enough to Protect Your Architecture

Files like CLAUDE.md and AGENTS.md can explain a project to coding agents, such as describing decisions like using Supabase Auth instead of Firebase UI components or keeping dependencies pointing inward. However, these files are still just instructions, not enforcement mechanisms. An AI agent can understand a rule yet still violate it during a large change, and humans are prone to the same mistakes.

The issue isn't solely with AI-generated code; AI agents make larger changes faster, increasing the likelihood of architectural drift going unnoticed. To address this, the author built ArchLint, an open-source CLI that checks Git changes against project architecture rules stored in the repository. The process involves: an AI agent or developer modifying code, generating a Git diff, and ArchLint checking the changes against defined rules.

These rules can be defined in a .archlint.yml file, specifying forbidden dependencies, import boundaries, and warnings. ArchLint works with any AI or human contributor since it evaluates the resulting Git diff, not the specific code changes. For example, a project can define rules like forbidding Firebase, preventing UI components from accessing database code, and highlighting authentication code changes for review.

Checking a change locally involves running npx archlint-ai init to create a starter configuration and then npx archlint-ai check to scan staged, unstaged, and untracked changes. When a rule is broken, ArchLint reports the rule, file, evidence, and message. The check can also be integrated into GitHub Actions to run automatically on pull requests.

If an error-level violation is detected, the pull request will fail. This approach allows the team to either fix the implementation to adhere to the existing architecture or modify the .archlint.yml file if the architecture itself has changed. The tool focuses on deterministic checks, evaluating only the new changes introduced in a pull request rather than scanning the entire repository.

Current limitations include support for JavaScript and TypeScript syntax, with future plans to expand to other programming languages. ArchLint is designed to complement, not replace, CLAUDE.md, AGENTS.md, architecture decision records, or code review. It handles enforceable decisions while allowing documentation and code review to handle the more nuanced aspects of architecture.

The project is available on GitHub at https://github.com/errrt/archlint, and feedback from developers using coding agents on real repositories is encouraged, particularly regarding which architecture rules they would want to enforce first.