Why CLAUDE.md Is Not Enough to Protect Your Architecture

说明与用途

CLAUDE.md 中的架构指令无法强制执行。ArchLint 工具检查 Git 变更以防止违反架构边界，例如添加禁止的依赖项或破坏分层结构。

问题

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.

结果

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.

工作流

• 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.

证据

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.

来源

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

来源

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.

来源