Prevent AI coding agents from introducing architectural drift. Use before
non-trivial features, refactors, cross-module fixes, new services, new
dependencies, schema changes, public API changes, or edits governed by a
change contract. Architecture Guardian is a local-first conformance workflow
with discovery, dependency rules, change contracts, baselines, scoped
expiring exceptions, and reuse-first search.
Prevent AI coding agents from introducing architectural drift. Use before
non-trivial features, refactors, cross-module fixes, new services, new
dependencies, schema changes, public API changes, or edits governed by a
change contract. Architecture Guardian is a local-first conformance workflow
with discovery, dependency rules, change contracts, baselines, scoped
expiring exceptions, and reuse-first search.
Architecture Guardian — Claude Skill
Use this skill in Claude Code before any non-trivial code change. The canonical
skill with all command references lives at
skills/architecture-guardian/SKILL.md.
Read the references under skills/architecture-guardian/references/ when a
specific capability is needed.
Required workflow:
Run agent-kernel architecture doctor . to confirm governance state is valid.
Run agent-kernel architecture discover . --json to see source roots and layers.
Search reuse candidates before creating a new capability:
agent-kernel architecture reuse "<business capability>" . --json.
Create or validate an active change contract for non-trivial work.
Implement only inside the approved scope. The Claude PreToolUse hook can
block writes outside an active contract.
Run agent-kernel architecture check . --json before commit.
Treat only new findings as regressions. Keep baseline debt visible.
Use scoped, expiring exceptions only after the user accepts the trade-off.
Capture repeated architectural failures as Failure Lessons.
Hard rules:
Do not create a second source of truth without evidence that responsibilities differ.
Do not move business rules into transport, UI, persistence, or framework layers.
Do not bypass an existing public interface to reach infrastructure directly.
Do not add dependencies that violate the reviewed layer graph.
Do not suppress findings without a reason, owner, scope, and expiry.
Do not treat a high aggregate score as permission to ignore one critical violation.
Do not block on low-confidence semantic guesses. Report them for review instead.
