arch-drift-guard

name	arch-drift-guard
description	Use when a repo is suffering architecture drift, API drift, main-file bloat, boundary erosion, or repeated breakage from cross-layer edits. Enforces artifact-first anti-drift governance: classify drift type, declare allowed change surface, write durable repo artifacts, require mechanical checks, and only then modify code.
tags	["architecture","drift","governance","anti-erosion","refactoring","large-repo"]
version	1

arch-drift-guard

When to use

Use this skill when any of the following appears:

• giant main.rs / god file keeps regrowing
• repeated API drift after partial refactors
• struct initializer drift after adding fields
• cross-layer edits keep breaking compile/tests
• module boundaries are unclear or routinely violated
• agent edits cause repo erosion over time
• user says things like: “漂移”, “越改越乱”, “边界不稳”, “模块化不够”

Do not use when

• simple isolated bug with clear local fix -> use systmt-dbggng
• brand-new system design -> use ddd-project-grdrls
• only one extraction move with known order in ict-engine main.rs -> consider ict-engi-stag-main-extr

Core rule

Do not start with code changes. First classify the drift, define the allowed change surface, and write the governing artifacts.

Drift classes

Classify the problem before touching code:

1. file-truncation-drift
   • file content is cut, reverted, or structurally broken
2. api-signature-drift
   • function signatures changed, call sites stale
3. struct-initializer-drift
   • new fields added, builders/defaults/tests stale
4. boundary-erosion
   • logic leaks across application/domain/reporting/orchestration layers
5. workflow-surface-drift
   • output/report/workflow snapshots evolve without synchronized adapters
6. dependency-drift
   • imports/dependencies move without declared layering rules

Mandatory artifact-first flow

Before significant edits, create or update repo artifacts:

• DEBUG.md for reproduction and evidence
• docs/architecture-boundaries.md for durable module/layer boundaries
• docs/change-surface.md for this task's allowed edit surface
• docs/drift-ledger.md for repeated erosion patterns and fixes

If the repo already has equivalent artifacts, update them instead of creating duplicates.

Allowed change surface

Define explicitly:

• files allowed to change
• files forbidden to change
• public interfaces allowed to move
• invariants that must remain stable
• tests/checks that must pass before expanding scope

If a fix requires touching files outside the declared surface, stop and revise the artifact first.

Required checks

Always prefer mechanical enforcement over prose. For each drift task, choose at least 2:

• compile/build check
• targeted test
• full test suite if surface is broad
• search for stale symbols/imports/call sites
• graph/dependency inspection
• diff audit on boundary-sensitive files

Anti-drift implementation order

1. restore file integrity first
2. restore type/build consistency
3. restore adapter/wrapper surfaces
4. restore module boundaries
5. only then add new feature work

Contract-first growth under external unknowns

Use this pattern when the target depends on real websites, browsers, callbacks, payment flows, or APIs whose runtime truth is not yet verified, and the user asks for “禁污染/禁负债” style progress:

1. Re-open docs/change-surface.md for each increment; make the current task, allowed files, forbidden files, completion criteria, and rollback trigger explicit.
2. Prefer pure contracts first: dataclasses, state machines, repository methods, schema tables, serializer helpers, and tests.
3. Keep unverified URL/DOM/network/API assumptions out of production services; place them only in probes/ or adapters/experimental/ after evidence exists.
4. Do not widen into pipeline, browser workers, or old giant scripts unless the change surface explicitly permits it.
5. Verify with targeted tests plus full suite/compile check when the surface touches models or storage; remove generated caches before finalizing.

Architecture guardrails

• One new field -> update struct, default, builders, tests, fixtures in one pass
• One new function signature -> patch all call sites immediately
• New reporting/output surface -> add adapter/helper first, do not inline giant logic into main.rs
• Repeated similar output blocks -> extract helper, do not wide-replace text
• If touching a god file, prefer unique helper insertion over direct large rewrites
• For Rust main.rs signature migrations, do not run broad textual close-paren replacements ()? vs })?) across the file. Use unique, per-callsite edits or AST-aware/manual patches; wide replacements can silently corrupt unrelated append_* / save_* calls.
• When modularizing a god-file CLI/workflow surface, extract pure value/surface builders first, then command functions later. Command handlers often depend on local loaders, refresh helpers, and private bootstrap glue; moving them first creates unresolved-boundary churn.
• Before moving a function out of a monolith, list its private dependencies explicitly: data loaders, snapshot refreshers, local helper views, and crate-path assumptions (crate::... vs binary-side ict_engine::...). If those are not portable yet, narrow the extraction surface.

Recommended repo artifacts

docs/architecture-boundaries.md

Include:

• layer list
• ownership of each layer
• forbidden dependency directions
• allowed adapter bridges
• “what does not belong here” examples

docs/change-surface.md

Include:

• task objective
• drift class
• editable paths
• non-editable paths
• verification commands
• rollback trigger

docs/drift-ledger.md

Append entries like:

• symptom
• root cause
• repair order that worked
• new permanent guardrail added

Validation standard

Minimum before claiming done:

• target compile/build passes
• no stale references in touched surfaces
• declared tests pass
• artifacts updated
• diff is scoped to declared surface or the surface artifact was revised

Escalation rule

If the same area has drifted 3+ times, stop treating it as a one-off bug. Create or update a durable architecture boundary artifact or a repo-specific skill.

Good outputs from this skill

• compact drift classification
• repo artifact updates
• small repair sequence
• boundary/ownership clarification
• mechanical checks listed and executed

Bad outputs

• vague “we should modularize more” with no artifact
• giant refactor started before classifying drift
• code changes without declared change surface
• relying on memory instead of repo truth

Suggested commands/checks

Use Hermes tools first, but typical shell verification may include:

• cargo fmt --all
• cargo check
• cargo test
• targeted test names
• targeted symbol searches for stale paths/signatures

Relationship to other skills

• use with systmt-dbggng when root cause still unknown
• use with ict-engi-stag-main-extr for large main.rs extraction in ict-engine
• use with ict-engi-safe-main-outp when drift is concentrated in output/reporting wiring
• use with ddd-project-grdrls if drift reveals missing strategic boundaries