Lint-as-architecture (standards = enforced rules)

Lint-as-architecture is the practice of encoding architectural decisions as custom lint rules that run in CI. Instead of communicating architecture through documentation (which people don't read) or code review comments (which are reactive and inconsistent), you express the decision as a machine-executable rule that fails the build when violated.

Consider these common architectural decisions that teams currently communicate through review comments:

• "Don't call the database directly from HTTP handlers - use the service layer"
• "All API responses must use our standard Result<T, ApiError> type"
• "The auth module must not import from billing - they're separate bounded contexts"
• "Don't use fmt.Println in production code - use the structured logger"
• "External HTTP calls must go through the HTTP client abstraction, not the standard library directly"

At L2, these rules exist as expectations in people's heads, enforced through review comments when a reviewer remembers to check. At L3 (Systematic), these rules are encoded in the linting configuration and enforced automatically by CI. The architectural constraint exists as code, not as institutional memory.

Tools that support custom rules: ESLint custom rules (JavaScript/TypeScript), Pylint plugins (Python), custom golangci-lint linters (Go), ArchUnit (Java/Kotlin), NetArchTest (.NET), Rubocop custom cops (Ruby), and many others. Most modern linting frameworks are designed to be extended with domain-specific rules.

The shift from L2 to L3 on this dimension is a mindset shift as much as a tooling shift: architecture is only real if it's enforced. A decision recorded in Confluence but not in CI is a suggestion, not a constraint.

Encoding architecture as executable rules has compounding benefits:

• Prevents regression - A constraint that exists only in institutional memory degrades over time. New team members don't know it. Existing team members forget it during a crunch. A lint rule enforces the constraint forever.
• Shifts enforcement left - Architectural violations caught in CI (seconds after commit) are dramatically cheaper to fix than violations caught in code review (hours later) or in production (days or weeks later).
• Makes architecture visible - The lint configuration is a machine-readable record of the team's architectural decisions. New team members can read the rules to understand what constraints exist and why.
• Enables faster code generation - When AI agents generate code at L4-L5, they often violate architectural constraints that aren't in their context. Custom lint rules catch these violations automatically, making AI code generation safer.
• Reduces reviewer cognitive load - Reviewers who know that architectural constraints are machine-enforced can stop mentally checking for violations. This is real cognitive capacity recovered for higher-order review.

The progression to L4 (auto-merge) and L5 (autonomous agents) depends critically on trusting your quality gate. Custom lint rules are a core component of that trust: they let you say with confidence that a Green PR has not introduced known architectural violations.

1. Identify your most repeated review comments - What architectural constraints do your reviewers enforce through comments? A quick analysis of your PR history will surface the top 5-10 repeated comment themes. These are the candidates for custom lint rules.
2. Start with one rule that enforces a clear boundary - Pick a simple, unambiguous constraint: "no imports from X module in Y module" or "no calls to this deprecated function." Write a custom lint rule for it. Getting one rule working teaches you the framework and demonstrates the value.
3. Choose the right tool for your language - For JavaScript/TypeScript, ESLint's custom rules API is well-documented. For Java/Kotlin, ArchUnit provides a fluent API for testing architectural constraints. For Python, Pylint plugins or custom AST visitors work well. For Go, golangci-lint's plugin system supports custom linters.
4. Test the lint rule before deploying - Write unit tests for the custom lint rule itself: cases that should fail, cases that should pass, edge cases. Lint rules with false positives will be disabled by frustrated developers.
5. Document the architectural decision alongside the rule - The lint rule codifies the decision, but the rule file should reference the decision's rationale. An ARCHITECTURE.md or inline comment explaining "why this rule exists" is essential for future team members.
6. Add new rules progressively - Don't try to encode all architectural decisions as lint rules at once. Add one per sprint, starting with the highest-impact (most frequently violated or most serious when violated) constraints. The process of writing lint rules also surfaces which architectural decisions are actually clear vs. ambiguous.

Writing lint rules that are too broad. A rule like "no direct database calls" that flags legitimate uses (in repository classes, for example) will generate false positives and be disabled. Rules need to distinguish between the allowed pattern and the forbidden pattern precisely. Spend time defining the exact pattern to flag before writing the rule.

Not maintaining custom rules. Custom lint rules break when the code they're analyzing changes structure. A rule that checks for a pattern that gets refactored away will either stop firing (false negatives) or start firing on unrelated code (false positives). Custom rules require maintenance. Assign ownership.

Using lint rules for things that belong in type systems. Some architectural constraints can be expressed in the type system (making illegal states unrepresentable) rather than in lint rules. A PaymentAmount type that wraps an integer can prevent "use raw integers for amounts" violations without a lint rule. Prefer type-system enforcement over lint-rule enforcement when possible - it's more robust.

Skipping the "why" - Lint rules without rationale are deleted by future developers who don't understand the constraint. "Why can't I import billing from auth?" If the rule doesn't explain, the developer disables it. Document the decision alongside the rule.