architecture-patterns by yonatangross/orchestkit
npx skills add https://github.com/yonatangross/orchestkit --skill architecture-patterns涵盖整洁架构、后端分层、项目结构约定和测试标准的统一架构验证与执行模式。每个类别在 references/ 目录下都有独立的规则文件,按需加载。
| 类别 | 规则数量 | 影响程度 | 适用场景 |
|---|---|---|---|
| 整洁架构 | 3 | 高 | SOLID 原则、六边形架构、端口与适配器、DDD |
| 项目结构 | 2 | 高 | 文件夹约定、嵌套深度、导入方向、Barrel 文件 |
| 后端分层 | 3 | 高 | 路由器/服务/仓储分离、依赖注入、文件命名 |
| 测试标准 | 3 | 中 | AAA 模式、命名约定、覆盖率阈值 |
| 规模适配 | 2 | 高 | 架构层级选择、防止过度工程、上下文感知执行 |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
# Clean Architecture: Dependency Inversion via Protocol
class IUserRepository(Protocol):
async def get_by_id(self, id: str) -> User | None: ...
class UserService:
def __init__(self, repo: IUserRepository):
self._repo = repo # Depends on abstraction, not concretion
# FastAPI DI chain: DB -> Repository -> Service
def get_user_service(db: AsyncSession = Depends(get_db)) -> UserService:
return UserService(PostgresUserRepository(db))
# Project Structure: Unidirectional Import Architecture
shared/lib -> components -> features -> app
(lowest) (highest)
# Backend Layers: Strict Separation
Routers (HTTP) -> Services (Business Logic) -> Repositories (Data Access)
SOLID 原则、六边形架构、端口与适配器,以及用于构建可维护后端的 DDD 战术模式。
| 规则 | 文件 | 关键模式 |
|---|---|---|
| 六边形架构 | ${CLAUDE_SKILL_DIR}/references/clean-hexagonal-ports-adapters.md | 驱动/被驱动端口、适配器实现、分层结构 |
| SOLID 与依赖规则 | ${CLAUDE_SKILL_DIR}/references/clean-solid-dependency-rule.md | 基于协议的接口、依赖倒置、FastAPI 依赖注入 |
| DDD 战术模式 | ${CLAUDE_SKILL_DIR}/references/clean-ddd-tactical-patterns.md | 实体、值对象、聚合根、领域事件 |
| 决策点 | 建议 |
|---|---|
| Protocol 对比 ABC | Protocol(结构化类型) |
| Dataclass 对比 Pydantic | 领域层用 Dataclass,API 层用 Pydantic |
| 仓储粒度 | 每个聚合根一个仓储 |
| 事务边界 | 服务层,而非仓储层 |
| 事件发布 | 在聚合中收集,提交后发布 |
基于功能的组织方式、最大嵌套深度、单向导入以及防止 Barrel 文件。
| 规则 | 文件 | 关键模式 |
|---|---|---|
| 文件夹结构与嵌套 | ${CLAUDE_SKILL_DIR}/references/structure-folder-conventions.md | React/Next.js 和 FastAPI 布局、最多 4 级嵌套、Barrel 文件规则 |
| 导入方向与位置 | ${CLAUDE_SKILL_DIR}/references/structure-import-direction.md | 单向导入、禁止跨功能导入、组件/钩子放置位置 |
| 规则 | 检查点 |
|---|---|
| 最大嵌套 | 从 src/ 或 app/ 开始最多 4 级 |
| 禁止 Barrel 文件 | 禁止 index.ts 重新导出(影响 Tree-Shaking) |
| 组件位置 | React 组件仅允许在 components/ 或 features/ 目录下 |
| 钩子位置 | 自定义钩子仅允许在 hooks/ 或 features/*/hooks/ 目录下 |
| 导入方向 | 单向:shared -> components -> features -> app |
采用 FastAPI 整洁架构,实现路由器/服务/仓储层分离及阻塞验证。
| 规则 | 文件 | 关键模式 |
|---|---|---|
| 分层分离 | ${CLAUDE_SKILL_DIR}/references/backend-layer-separation.md | 路由器/服务/仓储边界、禁止模式、异步规则 |
| 依赖注入 | ${CLAUDE_SKILL_DIR}/references/backend-dependency-injection.md | Depends() 链、认证模式、使用依赖注入覆盖进行测试 |
| 文件命名与异常 | ${CLAUDE_SKILL_DIR}/references/backend-naming-exceptions.md | 命名约定、领域异常、违规检测 |
| 层级 | 职责 | 禁止行为 |
|---|---|---|
| 路由器 | HTTP 相关、请求解析、认证检查 | 数据库操作、业务逻辑 |
| 服务 | 业务逻辑、验证、编排 | HTTPException、Request 对象 |
| 仓储 | 数据访问、查询、持久化 | HTTP 相关、业务逻辑 |
遵循 AAA 模式、命名约定、隔离和覆盖率阈值的测试最佳实践。
| 规则 | 文件 | 关键模式 |
|---|---|---|
| AAA 模式与隔离 | ${CLAUDE_SKILL_DIR}/references/testing-aaa-isolation.md | Arrange-Act-Assert、测试隔离、参数化测试 |
| 命名约定 | ${CLAUDE_SKILL_DIR}/references/testing-naming-conventions.md | 适用于 Python 和 TypeScript 的描述性、行为导向的命名 |
| 覆盖率与位置 | ${CLAUDE_SKILL_DIR}/references/testing-coverage-location.md | 覆盖率阈值、夹具作用域、测试文件放置规则 |
| 范围 | 最低要求 | 目标 |
|---|---|---|
| 总体 | 80% | 90% |
| 业务逻辑 | 90% | 100% |
| 关键路径 | 95% | 100% |
| 新增代码 | 100% | 100% |
上下文感知的后端架构执行。规则会根据 scope-appropriate-architecture 检测到的项目层级调整严格程度。
执行流程:
scope-appropriate-architecture 上下文读取项目层级(在头脑风暴/实现步骤 0 中设置)Read("${CLAUDE_SKILL_DIR}/rules/right-sizing-tiers.md") 中的信号自动检测| 规则 | 文件 | 关键模式 |
|---|---|---|
| 架构规模层级 | ${CLAUDE_SKILL_DIR}/rules/right-sizing-tiers.md | 面试/MVP/生产/企业规模矩阵、代码行数估算、检测信号 |
| 规模适配决策指南 | ${CLAUDE_SKILL_DIR}/rules/right-sizing-decision.md | 各层级的 ORM、认证、错误处理、测试建议,以及过度工程成本 |
| 规则 | 面试 | MVP | 生产 | 企业 |
|---|---|---|---|---|
| 分层分离 | OFF | WARN | BLOCK | BLOCK |
| 仓储模式 | OFF | OFF | WARN | BLOCK |
| 领域异常 | OFF | OFF | BLOCK | BLOCK |
| 依赖注入 | OFF | WARN | BLOCK | BLOCK |
| OpenAPI 文档 | OFF | OFF | WARN | BLOCK |
手动覆盖: 用户可以显式设置层级以绕过自动检测(例如,“我希望在这个家庭作业中使用企业模式来展示技能”)。
Is this a take-home or hackathon?
YES --> Flat architecture. Single file or 3-5 files. Done.
NO -->
Is this a prototype or MVP with < 3 months runway?
YES --> Simple layered. Routes + services + models. No abstractions.
NO -->
Do you have > 5 engineers or complex domain rules?
YES --> Clean architecture with ports/adapters.
NO --> Layered architecture. Add abstractions only when pain appears.
并非所有项目都需要架构模式。根据项目层级匹配复杂度:
| 模式 | 面试 | 黑客松 | MVP | 成长期 | 企业级 | 更简单的替代方案 |
|---|---|---|---|---|---|---|
| 仓储模式 | 过度(约 200 行代码) | 过度 | 临界 | 合适 | 必需 | 在服务中直接调用 ORM(约 20 行代码) |
| 依赖注入容器 | 过度(约 150 行代码) | 过度 | 仅轻量 | 合适 | 必需 | 构造函数参数或模块级单例(约 10 行代码) |
| 事件驱动架构 | 过度(约 300 行代码) | 过度 | 过度 | 选择性 | 合适 | 服务间直接函数调用(约 30 行代码) |
| 六边形架构 | 过度(约 400 行代码) | 过度 | 过度 | 临界 | 合适 | 使用导入的扁平模块(约 50 行代码) |
| 严格分层分离 | 过度(约 250 行代码) | 过度 | 警告 | 阻塞 | 阻塞 | 路由和模型在同一文件中(约 40 行代码) |
| 领域异常 | 过度(约 100 行代码) | 过度 | 过度 | 阻塞 | 阻塞 | 内置 ValueError/HTTPException(约 5 行代码) |
经验法则: 如果某个模式对于检测到的层级显示为“过度”,则不要使用它。使用更简单的替代方案。一个使用六边形架构的家庭作业传递的是过度工程的信号,而非技能。
# CLEAN ARCHITECTURE
# NEVER import infrastructure in domain layer
from app.infrastructure.database import engine # In domain layer!
# NEVER leak ORM models to API layer
@router.get("/users/{id}")
async def get_user(id: str, db: Session) -> UserModel: # Returns ORM model!
# NEVER have domain depend on framework
from fastapi import HTTPException
class UserService:
def get(self, id: str):
raise HTTPException(404) # Framework in domain!
# PROJECT STRUCTURE
# NEVER create files deeper than 4 levels from src/
# NEVER create barrel files (index.ts re-exports)
# NEVER import from higher layers (features importing from app)
# NEVER import across features (use shared/ for common code)
# BACKEND LAYERS
# NEVER use database operations in routers
# NEVER raise HTTPException in services
# NEVER instantiate services without Depends()
# TEST STANDARDS
# NEVER mix test files with source code
# NEVER use non-descriptive test names (test1, test, works)
# NEVER share mutable state between tests without reset
ork:scope-appropriate-architecture - 驱动规模适配执行的项目层级检测ork:quality-gates - YAGNI 门使用层级上下文验证复杂度ork:distributed-systems - 分布式锁、弹性、幂等性模式ork:api-design - REST API 设计、版本控制、错误处理ork:testing-unit - 单元测试:AAA 模式、夹具、模拟、工厂ork:testing-e2e - 端到端测试:Playwright、页面对象、视觉回归ork:testing-integration - 集成测试:API 端点、数据库、契约ork:python-backend - FastAPI、SQLAlchemy、asyncio 模式ork:database-patterns - 模式设计、查询优化、迁移每周安装次数
86
代码仓库
GitHub 星标数
132
首次出现
2026年2月14日
安全审计
安装于
github-copilot82
opencode82
gemini-cli81
codex79
cursor77
kimi-cli76
Consolidated architecture validation and enforcement patterns covering clean architecture, backend layer separation, project structure conventions, and test standards. Each category has individual rule files in references/ loaded on-demand.
| Category | Rules | Impact | When to Use |
|---|---|---|---|
| Clean Architecture | 3 | HIGH | SOLID principles, hexagonal architecture, ports & adapters, DDD |
| Project Structure | 2 | HIGH | Folder conventions, nesting depth, import direction, barrel files |
| Backend Layers | 3 | HIGH | Router/service/repository separation, DI, file naming |
| Test Standards | 3 | MEDIUM | AAA pattern, naming conventions, coverage thresholds |
| Right-Sizing | 2 | HIGH | Architecture tier selection, over-engineering prevention, context-aware enforcement |
Total: 13 rules across 5 categories
# Clean Architecture: Dependency Inversion via Protocol
class IUserRepository(Protocol):
async def get_by_id(self, id: str) -> User | None: ...
class UserService:
def __init__(self, repo: IUserRepository):
self._repo = repo # Depends on abstraction, not concretion
# FastAPI DI chain: DB -> Repository -> Service
def get_user_service(db: AsyncSession = Depends(get_db)) -> UserService:
return UserService(PostgresUserRepository(db))
# Project Structure: Unidirectional Import Architecture
shared/lib -> components -> features -> app
(lowest) (highest)
# Backend Layers: Strict Separation
Routers (HTTP) -> Services (Business Logic) -> Repositories (Data Access)
SOLID principles, hexagonal architecture, ports and adapters, and DDD tactical patterns for maintainable backends.
| Rule | File | Key Pattern |
|---|---|---|
| Hexagonal Architecture | ${CLAUDE_SKILL_DIR}/references/clean-hexagonal-ports-adapters.md | Driving/driven ports, adapter implementations, layer structure |
| SOLID & Dependency Rule | ${CLAUDE_SKILL_DIR}/references/clean-solid-dependency-rule.md | Protocol-based interfaces, dependency inversion, FastAPI DI |
| DDD Tactical Patterns | ${CLAUDE_SKILL_DIR}/references/clean-ddd-tactical-patterns.md | Entities, value objects, aggregate roots, domain events |
| Decision | Recommendation |
|---|---|
| Protocol vs ABC | Protocol (structural typing) |
| Dataclass vs Pydantic | Dataclass for domain, Pydantic for API |
| Repository granularity | One per aggregate root |
| Transaction boundary | Service layer, not repository |
| Event publishing | Collect in aggregate, publish after commit |
Feature-based organization, max nesting depth, unidirectional imports, and barrel file prevention.
| Rule | File | Key Pattern |
|---|---|---|
| Folder Structure & Nesting | ${CLAUDE_SKILL_DIR}/references/structure-folder-conventions.md | React/Next.js and FastAPI layouts, 4-level max nesting, barrel file rules |
| Import Direction & Location | ${CLAUDE_SKILL_DIR}/references/structure-import-direction.md | Unidirectional imports, cross-feature prevention, component/hook placement |
| Rule | Check |
|---|---|
| Max Nesting | Max 4 levels from src/ or app/ |
| No Barrel Files | No index.ts re-exports (tree-shaking issues) |
| Component Location | React components in components/ or features/ only |
| Hook Location | Custom hooks in hooks/ or features/*/hooks/ only |
| Import Direction | Unidirectional: shared -> components -> features -> app |
FastAPI Clean Architecture with router/service/repository layer separation and blocking validation.
| Rule | File | Key Pattern |
|---|---|---|
| Layer Separation | ${CLAUDE_SKILL_DIR}/references/backend-layer-separation.md | Router/service/repository boundaries, forbidden patterns, async rules |
| Dependency Injection | ${CLAUDE_SKILL_DIR}/references/backend-dependency-injection.md | Depends() chains, auth patterns, testing with DI overrides |
| File Naming & Exceptions | ${CLAUDE_SKILL_DIR}/references/backend-naming-exceptions.md | Naming conventions, domain exceptions, violation detection |
| Layer | Responsibility | Forbidden |
|---|---|---|
| Routers | HTTP concerns, request parsing, auth checks | Database operations, business logic |
| Services | Business logic, validation, orchestration | HTTPException, Request objects |
| Repositories | Data access, queries, persistence | HTTP concerns, business logic |
Testing best practices with AAA pattern, naming conventions, isolation, and coverage thresholds.
| Rule | File | Key Pattern |
|---|---|---|
| AAA Pattern & Isolation | ${CLAUDE_SKILL_DIR}/references/testing-aaa-isolation.md | Arrange-Act-Assert, test isolation, parameterized tests |
| Naming Conventions | ${CLAUDE_SKILL_DIR}/references/testing-naming-conventions.md | Descriptive behavior-focused names for Python and TypeScript |
| Coverage & Location | ${CLAUDE_SKILL_DIR}/references/testing-coverage-location.md | Coverage thresholds, fixture scopes, test file placement rules |
| Area | Minimum | Target |
|---|---|---|
| Overall | 80% | 90% |
| Business Logic | 90% | 100% |
| Critical Paths | 95% | 100% |
| New Code | 100% | 100% |
Context-aware backend architecture enforcement. Rules adjust strictness based on project tier detected by scope-appropriate-architecture.
Enforcement procedure:
scope-appropriate-architecture context (set during brainstorm/implement Step 0)Read("${CLAUDE_SKILL_DIR}/rules/right-sizing-tiers.md")| Rule | File | Key Pattern |
|---|---|---|
| Architecture Sizing Tiers | ${CLAUDE_SKILL_DIR}/rules/right-sizing-tiers.md | Interview/MVP/production/enterprise sizing matrix, LOC estimates, detection signals |
| Right-Sizing Decision Guide | ${CLAUDE_SKILL_DIR}/rules/right-sizing-decision.md | ORM, auth, error handling, testing recommendations per tier, over-engineering tax |
| Rule | Interview | MVP | Production | Enterprise |
|---|---|---|---|---|
| Layer separation | OFF | WARN | BLOCK | BLOCK |
| Repository pattern | OFF | OFF | WARN | BLOCK |
| Domain exceptions | OFF | OFF | BLOCK | BLOCK |
| Dependency injection | OFF | WARN | BLOCK | BLOCK |
| OpenAPI documentation | OFF | OFF | WARN | BLOCK |
Manual override: User can set tier explicitly to bypass auto-detection (e.g., "I want enterprise patterns for this take-home to demonstrate skill").
Is this a take-home or hackathon?
YES --> Flat architecture. Single file or 3-5 files. Done.
NO -->
Is this a prototype or MVP with < 3 months runway?
YES --> Simple layered. Routes + services + models. No abstractions.
NO -->
Do you have > 5 engineers or complex domain rules?
YES --> Clean architecture with ports/adapters.
NO --> Layered architecture. Add abstractions only when pain appears.
Not every project needs architecture patterns. Match complexity to project tier:
| Pattern | Interview | Hackathon | MVP | Growth | Enterprise | Simpler Alternative |
|---|---|---|---|---|---|---|
| Repository pattern | OVERKILL (~200 LOC) | OVERKILL | BORDERLINE | APPROPRIATE | REQUIRED | Direct ORM calls in service (~20 LOC) |
| DI containers | OVERKILL (~150 LOC) | OVERKILL | LIGHT ONLY | APPROPRIATE | REQUIRED | Constructor params or module-level singletons (~10 LOC) |
| Event-driven arch | OVERKILL (~300 LOC) | OVERKILL | OVERKILL | SELECTIVE | APPROPRIATE | Direct function calls between services (~30 LOC) |
| Hexagonal architecture | OVERKILL (~400 LOC) |
Rule of thumb: If a pattern shows OVERKILL for the detected tier, do NOT use it. Use the simpler alternative. A take-home with hexagonal architecture signals over-engineering, not skill.
# CLEAN ARCHITECTURE
# NEVER import infrastructure in domain layer
from app.infrastructure.database import engine # In domain layer!
# NEVER leak ORM models to API layer
@router.get("/users/{id}")
async def get_user(id: str, db: Session) -> UserModel: # Returns ORM model!
# NEVER have domain depend on framework
from fastapi import HTTPException
class UserService:
def get(self, id: str):
raise HTTPException(404) # Framework in domain!
# PROJECT STRUCTURE
# NEVER create files deeper than 4 levels from src/
# NEVER create barrel files (index.ts re-exports)
# NEVER import from higher layers (features importing from app)
# NEVER import across features (use shared/ for common code)
# BACKEND LAYERS
# NEVER use database operations in routers
# NEVER raise HTTPException in services
# NEVER instantiate services without Depends()
# TEST STANDARDS
# NEVER mix test files with source code
# NEVER use non-descriptive test names (test1, test, works)
# NEVER share mutable state between tests without reset
ork:scope-appropriate-architecture - Project tier detection that drives right-sizing enforcementork:quality-gates - YAGNI gate uses tier context to validate complexityork:distributed-systems - Distributed locking, resilience, idempotency patternsork:api-design - REST API design, versioning, error handlingork:testing-unit - Unit testing: AAA pattern, fixtures, mocking, factoriesork:testing-e2e - E2E testing: Playwright, page objects, visual regressionork:testing-integration - Integration testing: API endpoints, database, contractsork:python-backend - FastAPI, SQLAlchemy, asyncio patternsork:database-patterns - Schema design, query optimization, migrationsWeekly Installs
86
Repository
GitHub Stars
132
First Seen
Feb 14, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
github-copilot82
opencode82
gemini-cli81
codex79
cursor77
kimi-cli76
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
120,000 周安装
LLM错误分析指南:如何系统化诊断和分类AI流水线故障
194 周安装
Nansen 持币者分析工具:评估代币持有者质量,识别聪明钱与散户信号
195 周安装
Symfony端到端测试工具:Panther与Playwright集成,实现自动化E2E测试与TDD开发
198 周安装
Microsoft Agent Framework:开源AI智能体与工作流平台,支持Python/C#跨平台开发
195 周安装
Flask Python Web开发专家指南:最佳实践、性能优化与API设计
202 周安装
LLM评估审计工具:诊断AI评估流程问题,生成优先级修复清单
197 周安装
| OVERKILL |
| OVERKILL |
| BORDERLINE |
| APPROPRIATE |
| Flat modules with imports (~50 LOC) |
| Strict layer separation | OVERKILL (~250 LOC) | OVERKILL | WARN | BLOCK | BLOCK | Routes + models in same file (~40 LOC) |
| Domain exceptions | OVERKILL (~100 LOC) | OVERKILL | OVERKILL | BLOCK | BLOCK | Built-in ValueError/HTTPException (~5 LOC) |