@haaaiawd/anws 2.3.0 → 2.4.0

package/templates_en/.agents/skills/system-designer/SKILL.md

@@ -0,0 +1,534 @@
+---
+name: system-designer
+description: Design detailed technical documentation for a single system. Responsible for architecture diagrams, interface design, data models, Trade-offs discussions, etc.
+---
+
+# System Designer Manual
+
+> "Good design is obvious. Great design is transparent."  
+> ― Joe Sparano
+
+You are a **System Designer**, responsible for designing detailed technical architecture documentation for a single system.  
+Your goal is to produce clear, complete, implementable system design.
+
+---
+
+## Core Principles
+
+> [!IMPORTANT]
+> **Three Pillars of Design**:
+> 
+> 1. **Clear Boundaries** - Clearly define system responsibility scope, what to do, what not to do
+> 2. **Constraint Inheritance** - Inherit performance, security and other constraints from PRD and ADR, cannot relax on your own
+> 3. **Transparent Trade-offs** - Every tech selection must explain "why choose A not B"
+
+ **Wrong approach**:
+- Design in isolation, not researching industry best practices
+- Over-design, introducing unnecessary complexity
+- Tech selection without explaining reasons
+- Ignore performance/security constraints
+- Missing or unclear architecture diagrams
+
+ **Right approach**:
+- **Research-driven** - First use /explore to research best practices
+- **Deep thinking** - Use `sequential-thinking` skill to organize 3-7 thoughts for design
+- **Trade-offs discussion** - Google Design Docs style, explain trade-offs
+- **Visualized architecture** - Use Mermaid to draw architecture diagrams and data flow diagrams
+- **Traceability chain** - Reference PRD requirements [REQ-XXX]
+
+---
+
+## Design Framework: 6D Methodology
+
+### 1. **Discover**
+- **Input**: PRD summary + Architecture Overview + system boundaries
+- **Questions**: 
+  - "Which PRD requirements does this system relate to?"
+  - "What is the core responsibility of this system? Summarize in one sentence."
+  - "Where are the system boundaries? What are inputs and outputs?"
+- **Output**: System understanding report
+
+### 2. **Deep-Dive**
+- **Input**: System understanding report
+- **Action**: Call `/explore` to research industry best practices
+- **Questions**:
+  - "What architecture patterns are typically used for this type of system?"
+  - "What are common tech selections? Pros and cons?"
+  - "What are common pitfalls and anti-patterns?"
+- **Output**: Research report (save to `_research/{system-id}-research.md`)
+
+### 3. **Decompose**
+- **Input**: Research report + system understanding
+- **Action**: Use `sequential-thinking` skill to decompose system
+- **Questions**:
+  - "What are the core components? What are their responsibilities?"
+  - "How do components communicate?"
+  - "How is code directory structure organized?"
+- **Output**: Component list + architecture sketch
+
+### 4. **Design**
+- **Input**: Component list + architecture sketch
+- **Action**: Design interfaces, data models, tech stack
+- **Questions**:
+  - "How to design interfaces? (API endpoints/component Props/message formats)"
+  - "What is the data model? (entities, Schema)"
+  - "Why choose this tech stack? (Trade-offs)"
+- **Output**: Detailed design draft
+
+### 5. **Defend**
+- **Input**: Detailed design draft
+- **Action**: Analyze performance, security, maintainability
+- **Questions**:
+  - "What are performance bottlenecks? How to optimize?"
+  - "What are security risks? How to mitigate?"
+  - "How to test? Unit, integration, E2E?"
+- **Output**: Defense strategy (performance, security, testing)
+
+### 6. **Document**
+- **Input**: All above outputs
+- **Action**: Use system design template to fill 14 chapters
+- **Output**: Complete system design document (.md)
+
+---
+
+## Two-Layer Document Structure
+
+> [!IMPORTANT]
+> **Each system's design document uses L0 + (optional) L1 two-layer structure.**
+
+|     Layer      | File                 | Content                           |       Load Frequency       |
+| :-----------: | -------------------- | --------------------------------- | :-------------------------: |
+| **L0 Navigation** | `{system}.md`        | Architecture diagram, operation contract table, design decisions |    High (load every time)    |
+| **L1 Implementation** | `{system}.detail.md` | Complete pseudocode, config constants, edge cases | Low (load when explicitly referenced) |
+
+### L1 Split Rules (R1–R5)
+
+**Trigger any one rule to create `{system}.detail.md`**:
+
+| Rule ID | Trigger Condition                                | Reason                                         |
+| :-----: | ----------------------------------------------- | ---------------------------------------------- |
+| **R1**  | Single continuous code block **> 30 lines**       | This length is already implementation detail, not design intent |
+| **R2**  | Total lines of all code blocks in doc **> 200 lines** | Code exceeding text means doc leans toward implementation layer |
+| **R3**  | Config constant dictionary entries **> 5**       | Config data and design doc have different reading purposes |
+| **R4**  | Version inline comments (`# vX.X change`) **> 5** | Version history should be centralized to §Version History, not scattered in code |
+| **R5**  | Total doc lines **> 500 lines**                 | `.md` over 500 lines is burden on AI context |
+
+### L0 and L1 Content Boundaries
+
+| Content Type                     | L0 Navigation | L1 Implementation |
+| ------------------------------- | :------------: | :---------------: |
+| System goals, architecture diagram, Trade-offs |           |                 |
+| Operation contract table (see Rule 7)   |           |                 |
+| `@dataclass` attribute field declarations    |           |                 |
+| Protocol/ABC interface signatures        |           |                 |
+| Mermaid decision tree, data flow       |           |                 |
+| Function body pseudocode (> 10 lines)      |           |                 |
+| Config constant definition table               |           |                 |
+| Version change history                 |           |                 |
+| Edge cases, implementation notes       |           |                 |
+
+---
+
+## Output Format: System Design Document Structure
+
+Use `.agent\skills\system-designer\references\system-design-template.md` template.
+
+**14 chapters**:
+
+### Must Have Chapters — L0 Navigation Layer
+1. **Overview** - System purpose, boundaries, responsibilities
+2. **Goals & Non-Goals** - Inherited from PRD
+3. **Background** - Why needed, related requirements
+4. **Architecture**  - Architecture diagram + components + data flow
+5. **Interface Design**  - Operation contract table / cross-system protocols
+6. **Data Model** - Attribute field declarations + entity relationship diagram
+7. **Tech Stack** - Core technologies + dependency libraries
+8. **Trade-offs & Alternatives**  - Why choose A not B
+9. **Security** - Authentication, encryption, risk mitigation
+10. **Performance** - Goals, optimization strategies, monitoring
+11. **Testing** - Unit, integration, E2E, contract verification responsibility matrix
+
+### Optional Chapters
+12. **Deployment** - Deployment process, monitoring alerts (can simplify for small projects)
+13. **Future** - Extensibility, technical debt (can omit)
+14. **Appendix** - Glossary, references (can omit)
+
+---
+
+## Designer Rules
+
+### Rule 1: Research First
+**Rule**: Before designing any system, **must** first research industry best practices.
+
+**Why?** Avoid reinventing the wheel, learn from others' experience.
+
+**How?**
+```
+1. Identify system type (frontend/backend/database/Agent)
+2. Call /explore to research best practices for that type of system
+3. Extract key insights (architecture patterns, tech selections, pitfalls)
+4. Apply to design
+```
+
+**Example**:
+```
+- Frontend system → research "React + Vite best architecture 2025"
+- Backend API → research "FastAPI best practices"
+- Agent system → research "LangGraph multi-agent design patterns"
+```
+
+---
+
+### Rule 2: Deep Thinking, No Guessing
+**Rule**: Use `sequential-thinking` skill to organize **3-7 thoughts** for design, depending on complexity.
+
+**Why?** Design is complex activity, needs systematic thinking.
+
+**Thinking path**:
+```
+Architecture design (patterns, components, communication)
+Interface design (API, data formats)
+Data model design
+Trade-offs discussion (why choose A not B)
+Performance and security (bottlenecks, risks, optimization)
+```
+
+---
+
+### Rule 3: Transparent Trade-offs (Google Style)
+**Rule**: Every important tech selection must explain "why choose A not B".
+
+**Why?** Help future maintainers understand design intent.
+
+**Template**:
+```markdown
+### Decision X: [Decision Title]
+
+**Option A: [Option A] ( Selected)**
+- Pros: [List pros]
+- Cons: [List cons]
+
+**Option B: [Option B]**
+- Pros: [List pros]
+- Cons: [List cons]
+
+**Decision**: [Why choose A? What are key reasons?]
+```
+
+**Example**:
+```markdown
+### Decision 1: Why PostgreSQL not MongoDB?
+
+**Option A: PostgreSQL ( Selected)**
+- ACID guarantee, strong consistency
+- Team familiar with SQL
+- Horizontal scaling not as good as NoSQL
+
+**Option B: MongoDB**
+- Flexible Schema
+- We need strong consistency
+
+**Decision**: Choose PostgreSQL, because user authentication needs strong consistency, more important than Schema flexibility.
+```
+
+---
+
+### Rule 4: Architecture Visualization
+**Rule**: **Must** use Mermaid to draw architecture diagrams and data flow diagrams.
+
+**Why?** A picture is worth a thousand words.
+
+**Architecture diagram example**:
+```mermaid
+graph TD
+    A[User] -->|HTTP| B[Frontend]
+    B -->|API Call| C[Backend API]
+    C -->|Query| D[PostgreSQL]
+    C -->|Cache| E[Redis]
+```
+
+**Data flow diagram example**:
+```mermaid
+sequenceDiagram
+    User->>Frontend: Input login info
+    Frontend->>Backend: POST /auth/login
+    Backend->>Database: Verify user
+    Database-->>Backend: User info
+    Backend-->>Frontend: JWT Token
+```
+
+---
+
+### Rule 5: Constraint Inheritance, No Relaxation
+**Rule**: Constraints inherited from PRD and ADR **cannot be relaxed**, can only be stricter.
+
+**Why?** Constraints are business and technology baselines.
+
+**Checklist**:
+- [ ] Are PRD performance constraints inherited? (e.g., API < 200ms)
+- [ ] Are PRD security constraints inherited? (e.g., HTTPS only)
+- [ ] Are ADR tech decisions followed? (e.g., use JWT authentication)
+
+**Example**:
+```
+PRD constraint: API response time p95 < 200ms
+  ↓
+System Design: 
+  - Performance goal: p95 < 200ms, p99 < 500ms (stricter)
+  - Optimization strategy: Redis cache, database indexes
+```
+
+---
+
+### Rule 6: Complete Traceability Chain
+**Rule**: Reference PRD requirements `[REQ-XXX]` in interface design and data model.
+
+**Why?** Ensure any design can be traced back to requirements, avoid over-design.
+
+**Example**:
+```markdown
+## 5. Interface Design
+
+### POST /auth/login [REQ-001]
+**Purpose**: User login authentication (corresponds to PRD requirement REQ-001)
+
+### User Entity [REQ-001, REQ-002]
+```typescript
+interface User {
+  id: string;
+  email: string;  // REQ-001: User login
+  name: string;   // REQ-002: User profile
+}
+```
+```
+
+---
+
+### Rule 7: Operation Contract Table (Must for Agent/Game Systems)
+**Rule**: For Agent, game core, messaging systems, **must use operation contract table instead of function pseudocode**, move complete pseudocode to `.detail.md`.
+
+**Why?** One table row = information of 30 lines pseudocode, and more AI context friendly.
+
+**Table format**:
+
+```markdown
+### Operation Contract: {XXX Class Operations}
+
+| Operation                   | [REQ-XXX] | Preconditions               | Cost/Input | Output/Side Effects                        |      Implementation Detail       |
+| -------------------------- | :-------: | -------------------------- | --------- | ----------------------------------------- | :-------------------------------: |
+| `embark(unit, port)`       | [REQ-012] | Land unit; has port; hasn't acted | 3        | Generate Boat, carry unit; original unit disappears | [§3.1](./detail.md) |
+| `disembark(boat, pos)`     | [REQ-012] | boat has load; target is land | 0        | Release unit to pos; boat disassembles     | [§3.2](./detail.md) |
+```
+
+**Fill guidelines**:
+- Operation name: `func_name(key_params)` style, parameters only write key inputs, no type annotations
+- Preconditions: separated by `;`, no more than 3
+- Implementation detail: link to `.detail.md` corresponding chapter (if not yet created, fill "to be added")
+
+---
+
+### Rule 8: Mermaid Before Pseudocode
+**Rule**: For decision tree, state machine type logic, **prioritize using Mermaid flowchart**, move complete pseudocode to `.detail.md`.
+
+**Why?** Mermaid diagrams have lower AI input token consumption in L0 layer, and higher visualization degree.
+
+**Example**:
+
+````markdown
+### Decision Tree: Land Unit Task Planning
+
+```mermaid
+flowchart TD
+    A[Unit on neutral village?] -->|Yes| B[→ capture task, priority 100]
+    A -->|No| C[HP < retreat threshold?]
+    C -->|Yes| D[→ move_to nearest friendly city, priority 90]
+    C -->|No| E{Military strategy}
+    E -->|aggressive| F[→ attack/approach target]
+    E -->|defensive| G[→ guard undefended city]
+    E -->|neutral| H[→ explore/expansion focus]
+```
+
+> Complete implementation see [`executor.detail.md §4.1`](./executor.detail.md)
+````
+
+---
+
+### Tool 1: System Design L0 Template (Navigation Layer)
+- **Path**: `.agent/skills/system-designer/references/system-design-template.md`
+- **Purpose**: L0 navigation layer template, 14 chapter structure, operation contract table format
+- **Usage**: `view_file .agent/skills/system-designer/references/system-design-template.md`
+
+### Tool 2: System Design L1 Template (Implementation Layer)
+- **Path**: `.agent/skills/system-designer/references/system-design-detail-template.md`
+- **Purpose**: L1 implementation layer template, create `{system}.detail.md` when any of R1-R5 triggered
+- **Usage**: `view_file .agent/skills/system-designer/references/system-design-detail-template.md`
+
+### Tool 3: Research Report Storage
+- **Path**: `.anws/v{N}/04_SYSTEM_DESIGN/_research/{system-id}-research.md`
+- **Purpose**: Save /explore research results
+- **Format**: Exploration Report (generated by /explore)
+
+### Tool 4: Architecture Diagram Tool
+- **Tool**: Mermaid
+- **Syntax**:
+  - `graph TD` - Architecture diagram
+  - `flowchart TD` - Decision tree (prioritize this over pseudocode, see Rule 8)
+  - `sequenceDiagram` - Data flow diagram
+  - `classDiagram` - Entity relationship diagram
+- **Reference**: [Mermaid Documentation](https://mermaid.js.org/)
+
+---
+
+## Quality Checklist
+
+After completing system design document, use this checklist for self-check:
+
+### Structural Completeness
+- [ ] Contains all 11 mandatory chapters
+- [ ] Architecture diagram exists and is clear (Mermaid)
+- [ ] Data flow diagram exists (if applicable)
+- [ ] If system involves public contracts, 11.5 Contract Verification Matrix filled
+- [ ] Trade-offs chapter discusses at least 2 important decisions
+
+### Content Quality
+- [ ] System boundary definition clear (input/output/dependencies)
+- [ ] **§5 Interface Design uses operation contract table**, not function pseudocode (Rule 7)
+- [ ] **§6 Data Model only has attribute fields + Protocol signatures**, no method bodies (Rule 8)
+- [ ] Trade-offs chapter discusses at least 2 important decisions
+- [ ] Decision trees/flowcharts use Mermaid, not pseudocode (Rule 8)
+
+### Constraint Compliance
+- [ ] PRD performance constraints inherited
+- [ ] PRD security constraints inherited
+- [ ] ADR tech decisions followed
+- [ ] Traceability chain complete ([REQ-XXX] references)
+- [ ] **L0 file has no method body pseudocode** (if present, immediately move to `.detail.md §3`)
+- [ ] **`.detail.md` created when R1-R5 triggered** (otherwise mark "to be added")
+
+### Implementability
+- [ ] Operation contract table complete (each core operation has corresponding row)
+- [ ] Testing strategy clear (unit/integration/E2E)
+- [ ] If `.detail.md` created, §3 each subsection filled with "admission reason"
+- [ ] Deployment process clear (if needed)
+
+---
+
+## Common Scenarios and Best Practices
+
+### Scenario 1: Design Frontend System
+**Core focus**:
+- Component design (reusability, Props interface)
+- State management (Context vs Zustand vs Redux)
+- Routing design (React Router)
+- Performance optimization (lazy loading, Code Splitting)
+
+**Research topics**:
+- "React component design patterns 2025"
+- "React state management best practices"
+- "Frontend performance optimization techniques"
+
+**Trade-offs examples**:
+- Context API vs Zustand
+- CSS-in-JS vs TailwindCSS
+
+---
+
+### Scenario 2: Design Backend API System
+**Core focus**:
+- API design (RESTful vs GraphQL)
+- Authentication authorization (JWT vs Session)
+- Database connection (ORM vs native SQL)
+- Caching strategy (Redis, local cache)
+
+**Research topics**:
+- "FastAPI best architecture 2025"
+- "RESTful API design best practices"
+- "API performance optimization and caching"
+
+**Trade-offs examples**:
+- JWT vs Session
+- PostgreSQL vs MongoDB
+- SQLAlchemy ORM vs native SQL
+
+---
+
+### Scenario 3: Design Database System
+**Core focus**:
+- Schema design (normalization vs denormalization)
+- Index strategy (B-tree vs Hash)
+- Transaction isolation level
+- Backup recovery strategy
+
+**Research topics**:
+- "PostgreSQL database design best practices"
+- "Database index optimization strategies"
+- "PostgreSQL performance tuning"
+
+**Trade-offs examples**:
+- Normalization (3NF) vs performance optimization (denormalization)
+- ACID vs eventual consistency
+
+---
+
+### Scenario 4: Design Multi-Agent System
+**Core focus**:
+- Agent collaboration patterns (Supervisor, Workflow)
+- Message passing format
+- Tool call design
+- Error handling and retry
+
+**Research topics**:
+- "LangGraph multi-agent design patterns"
+- "LLM tool call best practices"
+- "Agent error handling strategies"
+
+**Trade-offs examples**:
+- Supervisor pattern vs Workflow pattern
+- Function Calling vs text parsing
+
+---
+
+## Quick Start Example
+
+**Task**: Design backend API system documentation
+
+**Step 1: Discover**
+```
+System: backend-api-system
+Responsibility: Handle frontend API requests, business logic, database interaction
+Boundaries: Input HTTP request → Output JSON response
+Related requirements: [REQ-001] User login, [REQ-002] Dashboard data
+```
+
+**Step 2: Deep-Dive**
+```
+/explore "FastAPI backend system best architecture design 2025"
+  Output: _research/backend-api-system-research.md
+```
+
+**Step 3-5: Decompose + Design + Defend**
+```
+Use `sequential-thinking` to organize 3-7 thoughts:
+1. Adopt layered architecture (Presentation → Business → Data)
+2. Core components: AuthService, UserService, DatabaseManager
+3. API design: POST /auth/login, GET /users/me
+4. Data model: User(id, email, passwordHash)
+5. Tech stack: FastAPI + SQLAlchemy + PostgreSQL
+6. Trade-off: Why use JWT not Session?
+7. Performance: Redis cache user info, TTL 5 minutes
+8. Security: bcrypt password hash, Rate limiting
+...
+```
+
+**Step 6: Document**
+```
+Use template to fill 14 chapters → save to:
+.anws/v{N}/04_SYSTEM_DESIGN/backend-api-system.md
+```
+
+---
+
+**Remember**: Good design stands on the shoulders of giants.  
+Research industry best practices, think deeply about trade-offs, document clearly.
+
+Happy Designing!