---
id: gh-guarding-architecture
name: "guarding-architecture"
url: https://skills.yangsir.net/skill/gh-guarding-architecture
author: riekelt
domain: ai-software-architecture-engineering
tags: ["architecture-guard", "architectural-invariants", "build-enforced-contracts", "dependency-guard", "design-principles"]
install_count: 17100
rating: 4.60 (120 reviews)
github: https://github.com/riekelt/principal-engineer/tree/main/plugins/principal-engineer/skills/guarding-architecture
---

# guarding-architecture

> 此技能用于守护软件架构的结构不变量，将关键约束编码为命名契约（陈述、理由、守卫）。当变更跨越模块边界、新增依赖方向、触及关键路径或与既定原则冲突时，自动生成可执行的架构测试与审查检查项，使违规在构建阶段被拦截，而非靠记忆或人工评审。它把『原则』从愿望提升为可强制执行的合同，确保系统长期保持可维护性与清晰边界。

**Stats**: 17,100 installs · 4.6/5 (120 reviews)

## Before / After 对比

### 架构违规从发现到修复的周期

**Before**:

在没有这个技能之前，开发者往往在代码评审时才发现架构边界被破坏，或者更糟，等到系统腐化后才意识到问题。每次违规都需要人工定位、讨论例外、追溯相关模块，周期漫长且依赖特定评审人的经验和记忆。

**After**:

使用了此技能后，架构不变量被编码为自动化守卫，每次构建都会机械地检查依赖方向、模块边界和关键约束。违规在提交或构建阶段立即暴露，反馈时间从数小时缩短到秒级，修复成本大幅下降，架构长期保持整洁。

| Metric | Before | After | Change |
|---|---|---|---|
| 违规发现周期 | 240分钟 | 5分钟 | -98% |

## Readme

# Guarding architecture

**REQUIRED BACKGROUND:** the `principal-engineering` skill.

## Overview

Structural invariants are load-bearing contracts: violating one surfaces as a class of bugs, not a single defect. Core principle: **an invariant that matters gets a name, a written rationale, and a mechanical guard; an invariant without a guard is a wish.**

## The pattern

1. **Name the invariants.** Numbered and citable ("Law 3"), each with a Statement (technology-neutral, meant to outlast any framework), a Rationale, and Implications. The rationale is a concrete failure narrative: the class of bugs that appears when the invariant is violated, told from an incident, not an abstraction. An invariant whose rationale nobody can state is one nobody will defend.
2. **Split the stable from the volatile.** The principles document changes rarely and names no classes; its current realization (the canonical owners, the guards, the reference designs) lives in a companion that changes with the code. When the two disagree, the invariant governs and the realization document gets corrected. The split keeps principles documents free of stale class names.
3. **Enforce mechanically.** Every enforceable invariant gets an architecture test that fails the build: dependency directions, package boundaries, layering rules, forbidden imports. What cannot be build-enforced becomes a named review check with the invariant cited. An invariant enforced by memory is enforced until the person who remembers it is on holiday.
4. **Violations mean redesign, never justification.** A design that violates a named invariant is wrong by construction: redesign it, do not argue the exception into the spec. Watering the contract down to match nonconforming code is the banned move; the violation gets recorded and the code gets fixed (the same rule the technical-writer plugin applies to normative documents).
5. **Specs show conformance.** A design that touches guarded ground names the invariants it touches and shows, per invariant, how it upholds each. This makes architecture review objective: the reviewer checks claims against named invariants instead of debating taste.
6. **Exceptions are amendments.** A genuine exception proposes an amendment, naming the invariant it bends and the boundary of the bend; silent exceptions are how an invariant becomes a suggestion. This is the only legal form of exception, and point 4 bans every other; an unreachable owner does not create one, so the change waits or lands conforming. A genuinely temporary exception is a dated waiver with an expiry condition and the owner's sign-off, recorded in the volatile realization document rather than by amending the stable invariant for a passing condition.
7. **An unexplained guard exclusion is a violation hidden from the build.** Whoever finds one surfaces it to the invariant's owner. An exclusion is never precedent for the next one, and extending an exclusion list "like the others did" ratifies erosion instead of following a pattern.

## Common invariant classes

Instances worth guarding in most systems, as examples rather than mandates:

- One canonical owner per concern (see `keeping-one-source-of-truth`).
- Dependency direction: the domain never imports the delivery mechanism.
- Critical-path isolation: no I/O and no slow or optional dependency on the hot path.
- Fail-closed boundaries: a gate that cannot evaluate must deny (see `handling-failures`).
- Migration immutability (see the hard rules in `principal-engineering`).

## Common mistakes

- A principles document full of class names. That is the realization document wearing the wrong title; split them.
- Adding the import "for now". Boundaries die by single convenient imports; the guard exists because each violation is locally reasonable.
- An invariant asserted in review but absent from the build. It will be enforced exactly as often as the right reviewer is present.
- Justifying a violation by the cost of conforming. The cost argument may be right, but its correct form is an amendment to the invariant, decided by the owner, recorded (via `recording-decisions` where installed), never a quiet exception in one spec.
- Principles written as taste ("prefer small modules") instead of contracts ("module X never imports module Y"). A contract can fail a build; taste can only fail a mood.


---
*Source: https://skills.yangsir.net/skill/gh-guarding-architecture*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-guarding-architecture/markdown*