architecture-design
Structured architectural design skill for the HypermediaEngine project. Use when translating requirements into architectural decisions, producing component designs, or documenting architectural trade-offs. Invoked by the software-architect agent to apply a consistent, systematic design process.
- License 许可
- GPL-3.0
- 最近更新
- 2026-06-06
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- architecture-design
- description
- Structured architectural design skill for the HypermediaEngine project. Use when translating requirements into architectural decisions, producing component designs, or documenting architectural trade-offs. Invoked by the software-architect agent to apply a consistent, systematic design process.
03 SKILL.md 正文
Architecture Design
You are executing the architecture-design skill on behalf of the software-architect agent. Your job is to produce a complete, grounded architectural design artifact based on the input provided.
Input
The calling agent will pass one of:
- A set of analyzed requirements (from requirement-analyst output)
- A description of a feature or subsystem to design
- A specific architectural question or decision to resolve
Process
Step 1 — Explore the Codebase
Before designing anything, ground yourself in the existing architecture:
- Use Glob to discover the current project structure
- Use Read on key files: middleware pipeline, DI registration, filter definitions, base types
- Use Grep to find established patterns:
{ data, error }return shape usage, middleware chain wiring, existing filter implementations - Identify what already exists that the new design must integrate with or extend
Step 2 — Identify Architectural Constraints
Extract constraints from the project conventions:
- Return shape must always be
{ data, error } - Explicit type declarations with target-typed new or collection expressions
- Async disposal over sync disposal
- No stack traces exposed to clients
- Logger module, not console output
- Must fit within: Middlewares, Dependency Injection, Endpoint Filters / Result Filters
Step 3 — Select Patterns
Choose architectural patterns appropriate to the requirements:
- Middleware pipeline — for cross-cutting concerns (auth, logging, error handling, transformation)
- Endpoint Filters — for per-endpoint request/response interception
- Result Filters — for transforming or enriching responses before they leave the pipeline
- Repository pattern — for data access abstraction
- CQRS — for separating read and write models when complexity warrants it
- DI-registered services — for stateless, reusable business logic components
Justify each pattern selection explicitly. Reject patterns that add complexity without a concrete benefit.
Step 4 — Produce the Design
Structure your output as follows:
Architecture Overview
High-level description of the proposed design in 3–5 sentences. State what the design achieves and how it fits into the existing system.
Component Breakdown
For each major component:
- Name: The component or class name
- Responsibility: Single, precise statement of what it does
- Interface: Key public surface (method signatures or contracts)
- DI Registration: Lifetime (Singleton / Scoped / Transient) and registration approach
- Dependencies: What it depends on and how those are injected
Data Flow
Step-by-step description of how a request moves through the system:
- Entry point (endpoint / middleware invocation)
- Filter / middleware chain steps in order
- Core logic execution
- Response construction using
{ data, error }shape - Exit point
Include error paths: what happens when a step fails, and how errors propagate without exposing stack traces.
Key Decisions
For each significant design choice, document:
- Decision: What was chosen
- Rationale: Why this option over alternatives
- Trade-off: What is given up
Risks and Mitigations
For each identified risk:
- Risk: Specific concern (not vague — name the failure mode)
- Likelihood: Low / Medium / High given this system's context
- Mitigation: Concrete design or implementation measure that addresses it
Implementation Guidance
Ordered list of implementation steps for the SoftwareEngineer agent, each referencing the relevant project conventions. Include:
- File/class creation order (dependency-first)
- DI registration location and approach
- Test strategy: what to unit test, what to integration test, mutation test coverage targets
Step 5 — Validate Against the Framework
Before returning the design, verify:
- [ ] Every component is reachable via DI — no
newfor services - [ ] All public response types use
{ data, error }shape - [ ] No synchronous disposal of disposable resources
- [ ] No stack trace exposure in error paths
- [ ] Design is testable — no hidden static dependencies or global state
- [ ] Mutation testing is viable — logic is isolated enough to be mutated and caught by tests
If any check fails, revise the relevant component before returning.
Output
Return the complete design artifact from Step 4, preceded by a one-line summary:
Design for: [feature/subsystem name] — [one sentence on the core architectural approach]
04 同仓库更多 Skills
write-tests
Test implementation skill for HypermediaEngine. Takes a confirmed test plan from design-test-cases and produces compilable, runnable xUnit tests following project conventions. Validates coverage quality through mutation testing. Invoked by the sqa-engineer agent after the test plan is approved.
write-documentation
Structured documentation writing workflow for HypermediaEngine. Writes or updates README.md files at the repo root and in each project directory (src/, tests/, samples/, etc.) based on current implementation, ADRs, and architecture decisions.
write-adr
Writes a numbered Architecture Decision Record (ADR) for a significant architectural choice in the HypermediaEngine project. Invoked by the software-architect agent whenever a consequential design decision is made or ratified. Saves the ADR to docs/architecture/decisions/.
tunit-playwright-ui-testing
Comprehensive guidance for writing coded end-to-end UI tests in C# using TUnit.Playwright. Tests inherit from PageTest — the base class manages all browser lifecycle. Covers NuGet setup, PageTest inheritance, Page Object Model, browser configuration, parallelism limiting, and CI integration. Based on the official TUnit docs at https://tunit.dev/docs/examples/playwright.
triage
Task classification, decomposition, dependency mapping, and routing skill. Invoked by the triage-agent to break any user request into discrete, independently-routable work items with assigned priorities and agent chains.
system-design
Expert system design skill. Use PROACTIVELY to design systems, review architectures, and assist software engineers in learning design principles and implementing them in the code with design patterns.