Architecture Patterns
KartikLabhshetwar/better-shot
Deep dive into software architecture for macOS. An agent skill from KartikLabhshetwar/better-shot.
Guides software architecture decisions, design patterns, and system design principles.
$ npx skills add CloudAI-X/opencode-workflow --skill designing-architecture -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install CloudAI-X/opencode-workflow designing-architecture --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/CloudAI-X/opencode-workflow.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/designing-architecture .claude/skills/designing-architecture && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "designing-architecture" agent skill from https://github.com/CloudAI-X/opencode-workflow/tree/main/skills/designing-architecture into .claude/skills/designing-architecture/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "designing-architecture", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/CloudAI-X/opencode-workflow/tree/main/skills/designing-architectureType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add CloudAI-X/opencode-workflow --skill designing-architecture -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install CloudAI-X/opencode-workflow designing-architecture --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/CloudAI-X/opencode-workflow.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/designing-architecture .agents/skills/designing-architecture && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "designing-architecture" agent skill from https://github.com/CloudAI-X/opencode-workflow/tree/main/skills/designing-architecture into .agents/skills/designing-architecture/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "designing-architecture", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add CloudAI-X/opencode-workflow --skill designing-architecture -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install CloudAI-X/opencode-workflow designing-architecture --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/CloudAI-X/opencode-workflow.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/designing-architecture .cursor/skills/designing-architecture && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "designing-architecture" agent skill from https://github.com/CloudAI-X/opencode-workflow/tree/main/skills/designing-architecture into .cursor/skills/designing-architecture/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "designing-architecture", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/CloudAI-X/opencode-workflow.git --path skills/designing-architecture--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add CloudAI-X/opencode-workflow --skill designing-architecture -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install CloudAI-X/opencode-workflow designing-architecture --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/CloudAI-X/opencode-workflow.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/designing-architecture .gemini/skills/designing-architecture && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "designing-architecture" agent skill from https://github.com/CloudAI-X/opencode-workflow/tree/main/skills/designing-architecture into .gemini/skills/designing-architecture/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "designing-architecture", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install CloudAI-X/opencode-workflow designing-architectureInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add CloudAI-X/opencode-workflow --skill designing-architecture -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/CloudAI-X/opencode-workflow.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/designing-architecture .github/skills/designing-architecture && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "designing-architecture" agent skill from https://github.com/CloudAI-X/opencode-workflow/tree/main/skills/designing-architecture into .github/skills/designing-architecture/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "designing-architecture", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add CloudAI-X/opencode-workflow --skill designing-architecture -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install CloudAI-X/opencode-workflow designing-architecture --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/CloudAI-X/opencode-workflow.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/designing-architecture .opencode/skills/designing-architecture && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "designing-architecture" agent skill from https://github.com/CloudAI-X/opencode-workflow/tree/main/skills/designing-architecture into .opencode/skills/designing-architecture/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "designing-architecture", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
designing-architectureGuides software architecture decisions, design patterns, and system design principles.
Designing Architecture is an agent skill from CloudAI-X/opencode-workflow. Guides software architecture decisions, design patterns, and system design principles. Use when designing systems, choosing patterns, or making architectural decisions.
Its SKILL.md is about 2.6k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts. Compatibility notes: opencode
It sits in Development, covering Design patterns and Software architecture. The licence is MIT.
8 steps, taken from the first numbered list in SKILL.md.
Read from SKILL.md and the folder at commit 0128ca6. It shows what the files ask for, not the result of running them.
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown).
From the folder's file list and the shell code blocks in SKILL.md.
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
opencode
From compatibility in the SKILL.md frontmatter.
Designing Architecture loads about 2.6k tokens when it runs. Until then it costs about 48 tokens; SKILL.md has 724 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
The full file from CloudAI-X/opencode-workflow at commit 0128ca6, republished under its MIT licence (© CloudAI-X). 724 words, ~2,631 tokens.
.claude/skills/designing-architecture/SKILL.md (or your agent's skills folder).Principles and patterns for designing maintainable, scalable, and robust software systems.
| Principle | Summary | Violation Sign |
|---|---|---|
| Single Responsibility | One reason to change | Class does too many things |
| Open/Closed | Open for extension, closed for modification | Modifying existing code for new features |
| Liskov Substitution | Subtypes replaceable for base types | Overrides break parent behavior |
| Interface Segregation | Small, focused interfaces | Classes implement unused methods |
| Dependency Inversion | Depend on abstractions | High-level modules depend on low-level |
Outer layers depend on inner layers, NEVER the reverse.
┌─────────────────────────────────────┐
│ Frameworks & Drivers │ ← Database, Web, UI
├─────────────────────────────────────┤
│ Interface Adapters │ ← Controllers, Presenters, Gateways
├─────────────────────────────────────┤
│ Application Business Rules │ ← Use Cases
├─────────────────────────────────────┤
│ Enterprise Business Rules │ ← Entities
└─────────────────────────────────────┘
Dependencies point INWARD only.┌─────────────────────────────────────┐
│ Presentation Layer │ ← UI, API Controllers
├─────────────────────────────────────┤
│ Application Layer │ ← Use Cases, Services
├─────────────────────────────────────┤
│ Domain Layer │ ← Business Logic, Entities
├─────────────────────────────────────┤
│ Infrastructure Layer │ ← Database, External APIs
└─────────────────────────────────────┘Use when: Traditional applications, clear separation needed Avoid when: High-performance needs, event-driven systems
┌───────────────┐
│ Primary │
│ Adapters │ ← REST API, CLI, GraphQL
└───────┬───────┘
│
┌──────────▼──────────┐
│ │
│ ┌───────────┐ │
│ │ Core │ │
Primary │ │ Domain │ │ Secondary
Ports │ │ Logic │ │ Ports
│ └───────────┘ │
│ │
└──────────┬──────────┘
│
┌───────▼───────┐
│ Secondary │
│ Adapters │ ← Database, Message Queue, External API
└───────────────┘Use when: Testability is critical, multiple interfaces needed Avoid when: Simple CRUD applications
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Service │ │ Service │ │ Service │
│ A │ │ B │ │ C │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
└────────────┴────────────┘
│
┌──────▼──────┐
│ Message │
│ Bus │
└─────────────┘Use when: Independent scaling, team autonomy, polyglot needs Avoid when: Small teams, simple domains, tight coupling required
Event Source → Event Bus → Event Handlers
│ │ │
▼ ▼ ▼
Produces Routes Events Consumes
Events (Kafka, RabbitMQ) EventsUse when: Async processing, decoupling, audit trails Avoid when: Immediate consistency required, simple workflows
| Pattern | Purpose | When to Use |
|---|---|---|
| Factory | Create objects without specifying class | Object creation logic is complex |
| Builder | Construct complex objects step-by-step | Many optional parameters |
| Singleton | Single instance globally | Shared resource (use sparingly) |
| Dependency Injection | Inject dependencies externally | Testability, loose coupling |
| Pattern | Purpose | When to Use |
|---|---|---|
| Adapter | Convert interface to another | Integrating incompatible systems |
| Decorator | Add behavior dynamically | Extending functionality without inheritance |
| Facade | Simplified interface to complex system | Hiding complexity |
| Repository | Abstract data access | Separating domain from persistence |
| Pattern | Purpose | When to Use |
|---|---|---|
| Strategy | Interchangeable algorithms | Multiple ways to do something |
| Observer | Notify dependents of changes | Event systems, reactive updates |
| Command | Encapsulate actions as objects | Undo/redo, queuing, logging |
| Chain of Responsibility | Pass request along handlers | Middleware, validation chains |
| Concept | Definition | Example |
|---|---|---|
| Bounded Context | Explicit boundary for a domain model | Order context, Shipping context |
| Ubiquitous Language | Shared vocabulary between devs and domain experts | "Order", "Line Item", "Fulfillment" |
| Context Map | How bounded contexts relate | Customer shared between Sales and Support |
| Pattern | Purpose | Example |
|---|---|---|
| Entity | Object with identity | User, Order |
| Value Object | Object without identity | Money, Address |
| Aggregate | Cluster of entities with root | Order + LineItems |
| Domain Event | Something that happened | OrderPlaced, PaymentReceived |
| Repository | Collection-like access to aggregates | OrderRepository |
| Domain Service | Logic that doesn't fit entities | PricingService |
| Pattern | Description | Trade-off |
|---|---|---|
| Horizontal Scaling | Add more instances | Statelessness required |
| Vertical Scaling | Bigger machines | Hardware limits |
| Caching | Store computed results | Cache invalidation |
| Database Sharding | Split data across DBs | Query complexity |
| Read Replicas | Separate read/write | Eventual consistency |
| CDN | Edge content delivery | Static content only |
| Pattern | Purpose | Implementation |
|---|---|---|
| Circuit Breaker | Prevent cascade failures | Fail fast when downstream is down |
| Retry with Backoff | Handle transient failures | Exponential delay between retries |
| Bulkhead | Isolate failures | Separate thread pools per dependency |
| Timeout | Bound waiting time | Max wait for responses |
| Fallback | Graceful degradation | Default behavior when service unavailable |
| Pattern | Consistency | Use When |
|---|---|---|
| ACID Transactions | Strong | Financial data, critical operations |
| Saga | Eventual | Distributed transactions |
| Event Sourcing | Eventual | Audit trails, complex state |
| CQRS | Eventual | Different read/write models |
| Need | Recommended | Avoid |
|---|---|---|
| Relational data, ACID | PostgreSQL, MySQL | MongoDB |
| Document storage, flexible schema | MongoDB, DynamoDB | Relational |
| Key-value, high speed | Redis, Memcached | Relational |
| Time series | InfluxDB, TimescaleDB | Generic SQL |
| Graph relationships | Neo4j, Neptune | Relational (for complex) |
| Search | Elasticsearch, Meilisearch | Full table scans |
| Need | Pattern |
|---|---|
| Async processing | Queue (SQS, RabbitMQ) |
| Event broadcasting | Pub/Sub (SNS, Kafka) |
| Task scheduling | Delayed queues |
| Load leveling | Queue with workers |
| Event sourcing | Log-based (Kafka) |
# ADR-001: [Title]
## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
## Context
[Why is this decision needed?]
## Decision
[What is the decision?]
## Consequences
### Positive
- [Benefit 1]
- [Benefit 2]
### Negative
- [Trade-off 1]
- [Trade-off 2]
## Alternatives Considered
1. [Alternative 1] - [Why rejected]
2. [Alternative 2] - [Why rejected]Before finalizing an architecture decision, verify:
SOLID:
S - Single Responsibility
O - Open/Closed
L - Liskov Substitution
I - Interface Segregation
D - Dependency Inversion
PATTERNS:
Layered → Simple, clear separation
Hexagonal → Testable, adaptable
Microservices → Scalable, independent
Event-Driven → Decoupled, async
DDD BUILDING BLOCKS:
Entity, Value Object, Aggregate
Repository, Domain Event, Domain Service
SCALABILITY:
Horizontal scaling, Caching, Sharding, CDN
RESILIENCE:
Circuit Breaker, Retry, Bulkhead, Timeout© CloudAI-X, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Just SKILL.md in skills/designing-architecture of CloudAI-X/opencode-workflow.
Open the folder on GitHubat commit 0128ca6
Designing Architecture next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Designing Architecture this skillCloudAI-X/opencode-workflow | 275 | — | ~2.6k | Automated safety check: Pass | MIT | |
| Architecture PatternsKartikLabhshetwar/better-shot | 2.4k | 2 repos | ~1.4k | Automated safety check: Pass | Custom licence | |
| Akka.Hosting Actor PatternsAaronontheweb/dotnet-skills | 1.2k | 1 repos | ~5k | Automated safety check: Pass | MIT | |
| Brooks Audithyhmrright/brooks-lint | 1.5k | 1 repos | ~537 | Automated safety check: Pass | MIT | |
| Adopt a Design PatternTotoro-jam/battle-tested-patterns | 345 | — | ~4.9k | Automated safety check: Pass | MIT | |
| Pattern Conformance AuditTotoro-jam/battle-tested-patterns | 345 | — | ~1.6k | Automated safety check: Pass | MIT |
KartikLabhshetwar/better-shot
Deep dive into software architecture for macOS. An agent skill from KartikLabhshetwar/better-shot.
Aaronontheweb/dotnet-skills
Shows how to build entity actors with Akka.Hosting so the same code runs in local unit tests and in a sharded cluster in production.
hyhmrright/brooks-lint
Architecture audit that maps module dependencies, checks layering integrity, and flags structural decay across a codebase, drawing on twelve classic engineering books.
Totoro-jam/battle-tested-patterns
Matches a coding problem to one of 46 documented systems patterns, checks that it really fits, then adapts it into your codebase with a test for its invariant.
Totoro-jam/battle-tested-patterns
Audits a codebase's existing patterns, such as rate limiters, circuit breakers and caches, against canonical invariants and flags mislabeled or divergent ones.
ciembor/agent-rules-books
Apply Martin Fowler-inspired enterprise architecture rules when choosing layers, service layers, transaction scripts, domain models, repositories, mappers, or…
CloudAI-X/opencode-workflow
Guides systematic project analysis, codebase exploration, and architecture pattern recognition.
CloudAI-X/opencode-workflow
Guides REST and GraphQL API design, endpoint patterns, request/response schemas, versioning, and API best practices.
CloudAI-X/opencode-workflow
Guides test strategy, TDD/BDD approaches, test coverage planning, and testing best practices.
CloudAI-X/opencode-workflow
Guides git workflows, branching strategies, commit conventions, and version control best practices.
CloudAI-X/opencode-workflow
Guides performance optimization, profiling techniques, and bottleneck identification.
CloudAI-X/opencode-workflow
CRITICAL skill for executing multiple Task tool calls in a SINGLE message for true parallelism.
Categories
Guides software architecture decisions, design patterns, and system design principles. Designing Architecture is an agent skill from CloudAI-X/opencode-workflow. Guides software architecture decisions, design patterns, and system design principles.
Designing Architecture fits situations like: designing systems; choosing patterns; making architectural decisions.
Run `npx skills add CloudAI-X/opencode-workflow --skill designing-architecture -a claude-code`. Or copy the skill folder (skills/designing-architecture in CloudAI-X/opencode-workflow) into .claude/skills/designing-architecture in your project. Claude Code loads it when a task matches its description.
Run `npx skills add CloudAI-X/opencode-workflow --skill designing-architecture -a codex`. Or copy the skill folder (skills/designing-architecture in CloudAI-X/opencode-workflow) into .agents/skills/designing-architecture in your project. Codex loads it when a task matches its description.
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add CloudAI-X/opencode-workflow --skill designing-architecture -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/designing-architecture, .gemini/skills/designing-architecture, .github/skills/designing-architecture and .opencode/skills/designing-architecture in your project.
SKILL.md names no scripts, command-line tools or credentials: Designing Architecture is instructions for the agent only. Compatibility (from SKILL.md): opencode.
SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
Designing Architecture is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.
About 2.6k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
Skills that share tags, products or a category with Designing Architecture: Architecture Patterns (KartikLabhshetwar/better-shot, 2.4k stars), Akka.Hosting Actor Patterns (Aaronontheweb/dotnet-skills, 1.2k stars), Brooks Audit (hyhmrright/brooks-lint, 1.5k stars) and Adopt a Design Pattern (Totoro-jam/battle-tested-patterns, 345 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
CloudAI-X (a GitHub user) maintains it in CloudAI-X/opencode-workflow, which has 275 GitHub stars. The repository holds 7 skills in this directory. The repository was last updated on January 10, 2026.
Source: CloudAI-X/opencode-workflow on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.