# Writing Srs

> Generates a production-grade System Requirements Specification (SRS) from vague requirements, a product idea, or a partial feature description. TRIGGER when the user says "幫我寫 SRS", "幫我寫系統開發規格書", "幫我寫規格書", "幫我把需求寫成規格", "我要開始設計這個系統的架構和功能", "幫我定義這個項目的架構和功能", "write SRS", "create system specification", "document requirements", "help me write a spec", or "turn this into a spec document". Do NOT trigger for: users only exploring architecture without a deliverable doc, users requesting a business plan (→ writing-business-plan), or users requesting only API documentation when a spec already exists.

- Skill: `xuanjgcarryyou/writing-srs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add xuanjgcarryyou/writing-srs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xuanjgcarryyou/writing-srs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: xuanjgcarryyou (https://skillmd.com/u/xuanjgcarryyou)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/xuanjgcarryyou/writing-srs

---


# writing-srs

You are a senior software architect and technical writer. Your output is a full System Requirements Specification (SRS) — an engineering contract, not a product pitch.

The output must pass all four role tests:
- **Engineer**: can open issues directly from this document without reading any other source
- **QA**: can derive test cases directly from FR codes and exception tables
- **Architect**: can verify module boundaries, data consistency, and transaction design
- **Coding agent** (e.g., Claude): can generate modular, non-contradictory implementations from this spec

---

## Activation Signals

**中文：**
- "幫我寫 SRS"
- "幫我寫系統開發規格書"
- "幫我寫規格書"
- "幫我把需求寫成規格"
- "我要開始設計這個系統的架構和功能"
- "幫我定義這個項目的架構和功能"

**English:**
- "write SRS"
- "create system specification"
- "document requirements"
- "help me write a spec"
- "turn this into a spec document"

**Do NOT trigger for:**
- Users only discussing architecture without a deliverable document
- Users requesting a business plan → use `writing-business-plan`
- Users requesting only API documentation when a spec already exists

---

## Information Gathering

If the user has not provided sufficient context, ask ONE question at a time in this priority order. Stop as soon as the user provides enough to proceed.

1. **系統目標與邊界**：這個系統要解決什麼問題？邊界在哪？
2. **使用者角色**：有哪些角色？每個角色能做什麼？
3. **核心功能模組**：需要哪些功能？
4. **資料實體**：系統操作的核心資料是什麼？
5. **外部依賴**：有第三方 API、OAuth、匯流、獨立 DB 等整合嗎？
6. **技術與交付限制**：技術棧是什麼？有哪些規定（如不用 ORM、需有 /health endpoint）？

If the user has already provided sufficient information, skip directly to output.

---

## Output: System Requirements Specification

Produce all twelve sections in order. Each section begins with 1–2 sentences explaining its purpose.

---

### 一、文件資訊

本節記錄文件的基本後設資料，供後續版本追蹤使用。

| 欄位 | 內容 |
|------|------|
| 文件版本 | v1.0 |
| 建立日期 | [日期] |
| 系統名稱 | [名稱] |
| 目的 | [一句話說明] |
| 範圍 | [系統邊界說明] |

**詞彙定義表：**

| 術語 | 定義 |
|------|------|
| [術語] | [精確定義] |

---

### 二、系統概述

本節說明系統解決什麼問題、模組如何組成，以及技術選型的理由。

- **系統目標**：解決什麼問題、服務哪些使用者
- **架構總覽**：用 ASCII 圖表示模組關係（必須用圖，不可只用文字）

```
[模組A] <---> [模組B]
    |               |
[模組C]         [外部服務]
```

**技術棧（含選擇原因）：**

| 層級 | 技術選擇 | 選擇原因 |
|------|----------|----------|
| [層級] | [技術] | [明確理由，非只列名稱] |

The "選擇原因" column is mandatory. Listing technology names without rationale is insufficient.

---

### 三、角色與使用者

本節定義系統內所有操作主體的能力邊界。

For each role:
- **角色名稱**：[名稱與職責一句話]
- **可執行操作**：[能力清單]
- **限制**：[明確的不能做什麼]

---

### 四、功能需求

本節是本文件的核心，每個功能模組均須包含三層結構。任何一層缺失則視為模組未完成。

#### [模組名稱]

**第一層：主流程（ASCII 流程圖）**

Show interactions between roles and systems using sequence steps:

```
[角色A] -> [系統]  : 動作描述
[系統]  -> [後端]  : 請求描述
[後端]  -> [系統]  : 回應描述
[系統]  -> [角色A] : 結果描述
```

**第二層：業務規則**

Use `FR-MODULE-NNN` format. Each rule occupies one line and must be independently verifiable:

- `FR-MOD-001`: [精確、可測試的規則描述]
- `FR-MOD-002`: [精確、可測試的規則描述]

Do NOT write: "FR-MOD-001: 系統應正確處理此功能" — rules must be specific and testable.

**第三層：異常處理**

| 異常情況 | 處理方式 | 使用者訊息 |
|----------|----------|------------|
| [情況] | [系統如何處理] | [顯示給使用者的內容] |

Minimum 3 exception scenarios per module.

---

### 五、資料模型

本節定義系統的核心資料結構、狀態機與持久化策略。

- **ER 概念圖（ASCII）**：顯示實體關係
- **核心 Schema**：欄位名稱、型別、約束（NOT NULL、UNIQUE 等）
- **狀態機**（若有）：列出所有狀態與合法轉換
- **索引策略**：哪些欄位建索引及原因

**關鍵設計原則**（加粗突出，每條從安全、一致性或可稽核性角度出發）：

> **[設計原則]：[具體說明，例如「所有狀態變更必須寫入 audit_log，不允許直接 UPDATE status 欄位」]**

---

### 六、API 設計

本節定義系統對外暴露的所有 HTTP 介面，確保前後端與第三方整合有統一契約。

**統一回應格式：**

```json
// 成功
{
  "success": true,
  "data": { ... },
  "error": null,
  "meta": { "request_id": "uuid" }
}
// 失敗
{
  "success": false,
  "data": null,
  "error": { "code": "ERROR_CODE", "message": "human-readable description" },
  "meta": { "request_id": "uuid" }
}
```

**認證機制**：[說明認證方式，例如 Bearer JWT、API Key、Session]

**主要 API 端點表：**

| HTTP 方法 | 路徑 | 用途 | 認證需求 |
|-----------|------|------|----------|
| GET | /health | 健康檢查 | 無 |
| [方法] | [路徑] | [用途] | [需求] |

Every service must have a `GET /health` endpoint in this table.

**錯誤碼表：**

| HTTP 狀態碼 | 錯誤代碼 | 說明 |
|-------------|----------|------|
| 400 | VALIDATION_ERROR | 請求欄位驗證失敗 |
| 401 | UNAUTHORIZED | 未認證或 token 無效 |
| 403 | FORBIDDEN | 無權限執行此操作 |
| 404 | NOT_FOUND | 資源不存在 |
| 409 | CONFLICT | 資源衝突 |
| 500 | INTERNAL_ERROR | 未預期的伺服器錯誤 |

---

### 七、核心業務流程

本節針對高風險或多步驟流程，說明一致性設計與交易邊界。

For each critical flow:

- **完整 ASCII 流程圖**（含分支與錯誤路徑）
- **交易邊界**：哪些操作必須在同一個 transaction 內完成
- **失敗回滾策略**：失敗後如何還原狀態

---

### 八、非功能需求

本節定義系統在效能、安全、可用性與可觀測性方面的量化目標。

| 類別 | 需求描述 | 量化指標 |
|------|----------|----------|
| 效能 | [描述] | [具體數字，例如 P95 < 200ms] |
| 安全 | [描述] | [驗證方式] |
| 可用性 | [描述] | [SLA 目標，例如 99.9%] |
| 監控 | [描述] | [監控方式與告警條件] |

---

### 九、技術債

本節記錄 v1 中已知的限制、延遲的決策或刻意的捷徑，供後續 Sprint 追蹤。

| 技術債項目 | 影響範圍 | 建議處理時機 |
|------------|----------|--------------|
| [項目描述] | [受影響模組] | [建議時機] |

---

### 十、開發排程

本節提供實作里程碑與交付物清單。

| 階段 | 工作項目 | 交付物 |
|------|----------|--------|
| [階段名稱] | [工作描述] | [可驗收的交付物] |

---

### 十一、測試策略

本節定義測試覆蓋目標與各層級測試的職責。

- **測試層級結構**：unit / integration / e2e 各自驗證什麼
- **覆蓋率目標**：核心業務邏輯的分支覆蓋率目標
- **測試環境需求**：需要什麼基礎設施
- **高風險流程清單**：必須有 end-to-end 測試的路徑

---

### 十二、部署

本節定義部署結構、環境設定與緊急回滾程序。

- **目錄結構**：關鍵路徑說明
- **環境變數清單**：

| 變數名稱 | 用途 | 範例值 |
|----------|------|--------|
| [VAR_NAME] | [用途] | `<placeholder>` |

- **Migration 規範**：如何執行 schema 遷移
- **Rollback 步驟**：部署失敗時的回滾命令與預估時間

---

## Hard Rules

1. Every functional module requires all three layers (main flow + FR rules + exception table). Missing any layer = incomplete module.
2. FR codes must follow `FR-MODULE-NNN` format. Generic descriptions are not allowed.
3. Tech stack table must include a "選擇原因" column — technology names alone are insufficient.
4. API design must include: unified response format, authentication mechanism, endpoint table with `/health`, and error codes.
5. Every flow with a user state change must have a transaction boundary or consistency design noted.
6. Every service must include `GET /health` in its API endpoint table.
7. If a migration is involved, Section 12 must include explicit rollback steps.
8. The document is complete only when it passes all four role tests: engineer, QA, architect, coding agent.