Design Document
- 2 installs
- 2.2k repo stars
- Updated July 27, 2026
- alibaba/loongcollector
design-document is a Claude skill that provides a fixed structure and conventions for writing technical design documents with Mermaid diagrams and unit-test tables.
About
This skill defines conventions for writing technical design documents. A developer uses it when authoring or reviewing a design doc to follow a fixed structure: background and problem statement, design goals, technical design (architecture, flowcharts, concurrency model, classes), error handling, deployment, and a unit-testing section. It mandates Mermaid diagrams and excludes project-management details like schedules.
- Defines a structured template for technical design documents
- Covers background, goals, architecture, concurrency model, and unit testing sections
- Requires Mermaid diagrams and a test-case table with mock dependencies
Design Document by the numbers
- 2 all-time installs (skills.sh)
- Ranked #1,294 of 1,879 Documentation skills by installs in the Skillselion catalog
- Data as of Aug 4, 2026 (Skillselion catalog sync)
design-document capabilities & compatibility
- Capabilities
- documentation
- Use cases
- documentation
- Pricing
- Free
What design-document says it does
Design document writing conventions. Use when writing or reviewing technical design documents.
**Do not** include project management info (estimates, schedules, milestones, Gantt charts)
npx skills add https://github.com/alibaba/loongcollector --skill design-documentAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 2 |
|---|---|
| repo stars | ★ 2.2k |
| Last updated | July 27, 2026 |
| Repository | alibaba/loongcollector ↗ |
What it does
Write or review a technical design document following a fixed section structure with Mermaid diagrams and test cases.
Who is it for?
Engineers writing or reviewing technical design documents with a consistent, testable structure
Skip if: Documents that need project-management info like estimates, schedules, milestones, or Gantt charts, which are explicitly excluded
When should I use this skill?
When writing or reviewing a technical design document
What you get
A structured design document covering background, goals, architecture, concurrency, error handling, and unit testing
- technical design document
- architecture diagrams
- unit-test case table
By the numbers
- 4 top-level sections (Background, Design Goals, Technical Design, Unit Testing)
Files
Design Document Conventions
1. Background / Problem Statement
1.1 Background and Pain Points
- Describe current system/module limitations and deficiencies
- List specific scenarios, metrics, or incident cases that triggered this design
1.2 Impact Scope
- Affected modules, microservices, APIs, data stores, third-party dependencies
- Potential impact on performance, reliability, cost, maintainability
- Forward/backward compatibility analysis
1.3 Constraints
- Compliance/security/performance/resource restrictions
- External system or infrastructure dependencies
---
2. Design Goals
2.1 Functional Goals
- List Must/Should/Could core capabilities by priority
2.2 Non-Functional Goals
- Performance (throughput, latency, concurrency, resource usage)
- Scalability, maintainability, testability, observability
- Reliability (fault tolerance, HA, degradation, rollback strategies)
2.3 Constraint Goals
- Backward compatibility, API stability
- Security and compliance requirements
---
3. Technical Design
3.1 Architecture Diagram
- Use Mermaid for high-level component diagrams with data/control flow
3.2 Detailed Flowcharts
- Key business flows, exception flows, retry/compensation with timing and triggers
3.3 Thread/Concurrency Model
- Thread lifecycle, inter-thread communication (locks, condition variables, queues, Actor patterns)
- Sequence diagrams for concurrency interactions
3.4 Core Classes and Data Structures
- Class diagrams showing main classes, interfaces, inheritance/composition relationships
- Key data structure fields, lifecycle, thread-safety strategy
3.5 Key Algorithms or Protocols
- Pseudocode or flow for pub/sub, load balancing, retry backoff, etc.
- State machine / protocol state transition diagrams
3.6 Error Handling and Recovery
- Error classification, exception stack, retry strategies, degradation plans
- Monitoring metrics, alert trigger conditions and levels
3.7 Deployment and Operations
- Configuration items, hot-update mechanisms, canary and rollback strategies
- CI/CD, container, Service Mesh, Kubernetes resource considerations
---
4. Unit Testing
4.1 Test Scope and Goals
- Cover core logic, boundary conditions, concurrency scenarios, exception paths
4.2 Test Environment and Tools
- Google Test/Mock version, necessary third-party stubs/fakes
4.3 Test Scenarios and Cases
| Case ID | Scenario | Input | Expected Output/Behavior | Mock Dependencies |
|---|---|---|---|---|
| TC-01 | Normal single log push | Single valid LogRecord | Returns SUCCESS, buffer size +1 | None |
| TC-02 | Buffer full | capacity=N filled | Throws BufferOverflowException | None |
| TC-03 | Concurrent push | Multi-thread simultaneous push | No data loss, order/final consistency matches design | MutexMock |
| TC-04 | flush clears | M items exist, then flush | Returns M items, buffer size=0 | TimeProviderMock |
4.4 Boundary and Exception Testing
- Empty input, invalid input, extreme capacity, network/disk fault injection
4.5 Performance Benchmarking (optional)
- Throughput, latency, CPU/Memory profile; comparison with baseline
---
Notes
- Do not include project management info (estimates, schedules, milestones, Gantt charts)
- Code examples must follow team C++ coding standards (see
.claude/skills/project-knowledge/) - Test case naming:
<Module>_<Function>_<Number>for CI coverage tracking
Related skills
Lark MarkdownInstantly turn any markdown file into clean, formatted Lark/Figma-compatible documents without manual reformatting.488k
Lark DocCreate, read, update, summarize, rewrite and manage Feishu/Lark cloud documents directly from agent workflows.401k16.1kLark WikiCreate, organize, query, and manage documents, spaces, and members inside Lark (Feishu) knowledge bases directly from AI agent workflows.397k16.1k
Domain ModelingBuild and sharpen a project's domain model: pin down domain terminology in a glossary and record architectural decisions as ADRs.318k202k
Opensource Guide CoachGet expert, attribution-safe guidance on launching and sustaining an open-source project.270k71Readme I18nMaintain consistent, updatable language selector blocks across every README variant in a multilingual repository.270k71FAQ
What should a design document exclude?
Project-management info such as estimates, schedules, milestones, and Gantt charts.
What diagramming tool does it require?
Mermaid, for high-level component diagrams and detailed flowcharts.