# 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.

- Skill: `majiayu000/architecture-guardian` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/architecture-guardian`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/architecture-guardian/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/architecture-guardian

---


# 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_CHECKING` imports (type hints only, no runtime dependency).
- Allow `domain.ports` imports in infrastructure (port protocols are contracts).
- Allow `domain.types` and `domain.exceptions` imports 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|Container\\.resolve" src/bioetl -g "*.py"` |
| 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
1. Read the target files (focus on changed files).
2. Check imports against the matrix above (ignore `TYPE_CHECKING`).
3. 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.
4. Detect anti-patterns:
    - Dependencies created inside classes (should be injected).
    - Direct `import structlog` in application/interfaces (use LoggerPort).
    - Sentinel values like `-1` or `"N/A"` (prefer `None`/Optional).
    - `print()` usage (use structured logging).
    - Hardcoded secrets.
5. Verify type annotations on public functions and methods.
6. 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
```bash
# 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
```markdown
## 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`).