AL-JANEF/janef-forge / skills/engineering/architecture-integrity
architecture-integrity
VerifiedDesign or change system structure without breaking invariants: module and domain boundaries, dependency direction, new services, queues, caches, datastores, or frameworks, and lasting trade-offs recorded as ADRs. Use when a change crosses components, introduces a durable boundary, or is hard to reverse.
Architecture Integrity
Architecture should reduce the cost of known change, not speculate about every future possibility. Preserve ownership, dependency direction, invariants, and clear boundaries; do not redesign unrelated layers to make a local change look cleaner.
Decision frame
- Which current and expected use cases must the design serve? Which quality attributes matter here: reliability, security, latency, scale, operability, portability, cost?
- What is the smallest boundary that localizes change without hiding essential behavior?
- Which option is easiest to test, observe, migrate, and remove?
- Start from requirements, trust boundaries, failure modes, deployment constraints, and the existing sources of truth.
Design rules
- Keep domain policy separate from transport, storage, framework, and vendor adapters.
- Depend toward stable contracts. Avoid circular dependencies, shared mutable authority, duplicated business rules, and cross-domain database ownership.
- Make ownership of data, transactions, retries, timeouts, and cleanup explicit.
- Do not introduce a service, queue, cache, datastore, framework, or abstraction unless the existing architecture cannot meet the requirement cleanly. Prefer boring, existing technology.
- Model failure, recovery, operability, and ownership, not only the happy path. Keep distributed systems no more complex than necessary.
- Design migrations for mixed versions, rollback, and partial failure. Add observability at boundaries where failures would otherwise be ambiguous.
Record the decision
Write an ADR in the repository's established mechanism when the choice affects multiple components, introduces infrastructure or a dependency, changes a public contract, has meaningful alternatives, or will be costly to reverse. Capture context, decision, alternatives, consequences, migration, and rollback. Do not turn the ADR into a tutorial.
Verify
Validate the architecture against implementation reality before claiming compliance: imports and dependency direction, ownership of data and transactions, and the actual deployment topology. A diagram that does not match the code is a finding.
Output
## Design: <scope>
Requirements & constraints: ...
Options considered: <A> / <B> — chosen <X> because ...
Boundaries & ownership: ...
Failure & migration model: ...
ADR: <path or "not needed because ...">
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |