skills.rest
Xerrion
XerrionCOMMUNITY
Explore all skills by this author →
Website𝕏@TheRealXerrionGitHub

architecture-philosophy

Define and enforce architectural structure using five laws for modules, dependencies, APIs, state, and failures.

Updated Mar 5, 2026
Search Tags:#architecture#modularity#design-principles#api-design#system-design#dependency-management
One-click install
npx skills add https://github.com/Xerrion/opencode --skill architecture-philosophy-xerrion
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: architecture-philosophy
Source: https://github.com/Xerrion/opencode/tree/main/skills/architecture-philosophy
Command: npx skills add https://github.com/Xerrion/opencode --skill architecture-philosophy-xerrion

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Establishes a principled approach to structural design so software systems remain coherent, scalable, and honest about dependencies, state ownership, and failure modes.

Core Features & Use Cases

  • Follow the Grain: Extend the existing structure instead of introducing new layers or patterns; maintain a consistent, repeatable architecture.
  • Strict Layer Direction: Ensure dependencies flow inward; prevent circular imports and cross-layer leakage.
  • Design APIs for the Caller: Provide stable, caller-focused interfaces that stay resilient to implementation changes.
  • One Authoritative Source Per State: Assign a single owner for mutable state; derive non-stable state where needed.
  • Explicit Failure Paths: Define explicit error flows for async boundaries and cross-service calls, enabling reliable recovery.

Quick Start

Apply the 5 Laws of Intentional Architecture when framing new modules or refactoring existing code to ensure coherent structure and clear ownership.

Frequently Asked Questions about architecture-philosophy

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I enforce strict layer direction and prevent circular imports in my system design?▼

Design APIs for the caller by providing stable, caller-focused interfaces that stay resilient to implementation changes. This approach ensures your API shape serves consumer needs rather than exposing internal structural details.

What is the best way to manage mutable state ownership across modules?▼

Assign one authoritative source per state by giving a single owner control of mutable state and deriving non-stable state where needed. This prevents state synchronization issues and duplicate ownership across module boundaries.

How do I define explicit failure paths for async boundaries and cross-service calls?▼

Define explicit failure paths by establishing clear error flows for async boundaries and cross-service calls, enabling reliable recovery. This ensures your architecture honestly handles failure modes rather than letting errors propagate silently.

When should I follow the grain instead of introducing new architectural layers?▼

Follow the grain by extending the existing structure instead of introducing new layers or patterns when framing new modules. This maintains a consistent, repeatable architecture and avoids unnecessary complexity in your system design.

Can I apply these design principles when refactoring existing code or only for new modules?▼

Apply the five laws of intentional architecture when framing new modules or refactoring existing code to ensure coherent structure and clear ownership. The principles work equally well for both greenfield development and legacy restructuring.

Related Skills

Explore More Software Engineering Skills→
HechaoYannetHechaoYannet

create-architecture

Generate a master architecture document from GDDs, ADRs, and governance constraints.

Community
Advanced
ssmleossmleo

govfolio-schema-contracts

Manage and verify domain schemas and OpenAPI contract boundaries for API services.

Community
Intermediate
GaryOcean428GaryOcean428

import-resolution

Identify and fix Python import errors and validate __init__.py exports.

Community
Intermediate
Artag-ChrisArtag-Chris
1

architecture-patterns

Guide backend architecture design with Clean Architecture, Hexagonal Architecture, and Domain-Driven Design.

Community
Advanced