Why CLAUDE.md Is Not Enough to Protect Your Architecture

Description and use

Architecture instructions in CLAUDE.md are not enforced. The ArchLint tool checks Git changes to prevent architectural violations, such as adding forbidden dependencies or breaking layer boundaries.

Problem

Architecture instructions in files like CLAUDE.md are not enforced. AI agents or developers can introduce architectural violations (e.g., adding forbidden dependencies or breaking layer boundaries) that pass tests and compile but degrade the system's structure.

Outcome

ArchLint converts architecture instructions into executable rules that check Git diffs. It prevents architectural drift by blocking violations in pull requests, ensuring that critical boundaries (dependencies, layers, auth paths) are maintained without requiring manual review for every change.

Workflow

• Define architecture rules in a .archlint.yml configuration file (e.g., forbid Firebase, block UI imports from DB, protect auth paths).
• Run the check locally from the repository root using npx archlint-ai check to validate staged, unstaged, and untracked changes.
• Integrate the check into CI/CD by adding a GitHub Actions workflow that runs npx archlint-ai check on every pull request.
• If a violation is detected, fix the implementation or explicitly update the .archlint.yml rule to reflect a changed architectural decision.

Evidence

ArchLint does not need to know whether the change came from Claude Code, Codex, Cursor, or a human contributor. It evaluates the resulting Git diff.

Source

If a pull request introduces an error-level violation, the command exits with a non-zero status and the check fails.

Source

ArchLint v0.1 therefore focuses on deterministic rules. It defines an experimental provider-neutral interface for future semantic checks, but the current package does not send repository code to an LLM.

Source