Agent skill
architecture-guardian
Validate BioETL architecture boundaries, ADR compliance, naming conventions, and anti-patterns. Use after any code changes affecting layer structure (domain, application, infrastructure, composition, interfaces), during refactors, or when reviewing PRs for architectural compliance.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/architecture-guardian-satorykono-bioactivitydataacqui
SKILL.md
Architecture Guardian
Objective
Protect the BioETL hexagonal architecture by auditing code changes for boundary violations, DI issues, naming conventions, and ADR compliance.
Core Responsibilities
- Validate import rules across layers.
- Check naming conventions for classes, functions, and modules.
- Detect anti-patterns (DI violations, direct logging, sentinel values, print usage, hardcoded secrets).
- Verify ADR compliance in
docs/02-architecture/decisions/. - Audit structural consistency (type annotations, module naming, delegation).
Layer Structure (Hexagonal + DDD)
interfaces/ -> composition/ -> application/ -> domain/ <- infrastructure/
Import Rules Matrix (Critical)
| From \ To | domain | application | infrastructure | composition | interfaces |
|---|---|---|---|---|---|
| domain | OK | NO | NO | NO | NO |
| application | OK | OK | NO | NO | NO |
| infrastructure | OK (ports only) | NO | OK | NO | NO |
| composition | OK | OK | OK | OK | NO |
| interfaces | OK | OK | OK | OK | OK |
Allowed Exceptions
- Allow
TYPE-CHECKINGimports (type hints only, no runtime dependency). - Allow
domain.portsimports in infrastructure (port protocols are contracts). - Allow
domain.typesanddomain.exceptionsimports everywhere.
DI Violations (Critical)
| ID | Pattern | Example | Detection |
|---|---|---|---|
| DI-V001 | Hard-coded constructor | self.client = ConcreteClass() |
rg "self\\.[a-z-]* = [A-Z][a-zA-Z]*\\(" src/bioetl/application -g "*.py" |
| DI-V002 | Method-level instantiation | def run(): client = Client() |
Inspect method bodies |
| DI-V003 | Service locator | ServiceLocator.get(), Container.resolve() |
`rg "Locator |
| DI-V004 | Import-time side effects | logger = structlog.get-logger() at module level |
Inspect module-level assignments |
| DI-V005 | Factory in business logic | Factory calls outside composition | Ensure factories exist only in composition/ |
Validation Workflow
- Read the target files (focus on changed files).
- Check imports against the matrix above (ignore
TYPE-CHECKING). - Verify naming conventions:
- Classes: PascalCase + suffix (Factory, Client, Protocol, Service, Transformer, Port, Error, Schema, Config).
- Functions: snake-case + prefix (get-, fetch-, create-, validate-, is-, has-, can-, iter-).
- Modules: lowercase-snake-case, no abbreviations.
- Detect anti-patterns:
- Dependencies created inside classes (should be injected).
- Direct
import structlogin application/interfaces (use LoggerPort). - Sentinel values like
-1or"N/A"(preferNone/Optional). print()usage (use structured logging).- Hardcoded secrets.
- Verify type annotations on public functions and methods.
- Generate a structured report with exact file:line references.
Valid Patterns (Do Not Flag)
- Optional parameters with defaults, for example
policy: Policy | None = None. - NoOp implementations (Null Object pattern for optional observability).
- Re-exports for compatibility, for example
from module import X; --all-- = ["X"]. - Large files that delegate responsibilities cleanly (size alone is not a god object).
- Graceful degradation with conservative fallback values when dependencies are unavailable.
- Int to float coercion in Gold schemas for nullable integers.
Verification Commands
# Import violations
rg "from bioetl\\.infrastructure" src/bioetl/application -g "*.py" | rg -v "TYPE-CHECKING"
rg "from bioetl\\.application" src/bioetl/infrastructure -g "*.py" | rg -v "TYPE-CHECKING"
# Anti-patterns
rg "print\\(" src/bioetl -g "*.py" | rg -v "# noqa"
rg "import structlog" src/bioetl/application -g "*.py"
# DI violations
rg "self\\.[a-z-]* = [A-Z][a-zA-Z]*\\(" src/bioetl/application -g "*.py"
rg "import structlog" src/bioetl/application src/bioetl/domain -g "*.py"
# Architecture checks
pytest tests/architecture/ -v
mypy src/bioetl/ --strict
Report Format
## Architecture Validation Report
**Date**: {YYYY-MM-DD HH:MM}
**Scope**: {files/directories checked}
**Status**: {PASS|FAIL|WARN}
### Summary
| Category | Issues | Severity |
|---|---|---|
| Import Violations | {N} | CRITICAL/MEDIUM/LOW |
| DI Violations | {N} | CRITICAL |
| Naming Violations | {N} | ... |
| Anti-Patterns | {N} | ... |
| Type Errors | {N} | ... |
### Critical Issues (Must Fix)
#### {Issue 1}
- **File**: `{path}:{line}`
- **Violation**: {description}
- **Rule**: {RULES.md section or ADR}
- **Fix**: {suggested fix with code}
### Verification
After fixes, run:
```bash
pytest tests/architecture/ -v
mypy src/bioetl/ --strict
make lint
## Constraints
### MUST
- Flag all import boundary violations (except `TYPE-CHECKING`).
- Provide exact file:line references.
- Suggest actionable fixes.
- Reference the relevant `RULES.md` section or ADR.
- Verify claims by reading actual code.
### MUST NOT
- Flag `TYPE-CHECKING` imports as violations.
- Flag the valid patterns listed above.
- Make assumptions without code verification.
- Report false positives (check `CLAUDE.md` section 2.3 for known non-issues).
- Allow any domain -> external imports.
- Accept hard-coded dependencies in application or domain layers.
### SHOULD
- Prioritize critical violations.
- Group related violations.
- Suggest automated fixes where possible.
- Consider project-specific context from `CLAUDE.md`.
## Double Verification Protocol
1. Read the actual code and assess structure and delegation.
2. Confirm every reported issue with exact file:line references.
## Operational Notes
- Prefer model "opus" if the harness supports model selection.
- UI accent color is green (configured via `agents/openai.yaml`).
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?