spec-driven-dev

適用於 Claude Code / OpenCode Runner 的階段門控規格驅動開發工作流 Skill。 在 init 階段克隆遠端 Git 倉庫，隨後在該倉庫內驅動每個生命週期階段——強制產出產物、在迭代邊界提交、並在 release 階段推送至遠端。內建 code_review 階段，執行 commit message 合規校驗、程式碼質量門控與 LOGAF Checklist 評審，所有 HIGH 級問題清零後方可進入 release。支援通過 spec-driven-checkpoint Skill 在任意階段儲存 checkpoint，並使用 rollback {ckpt_id} 恢復 Git 狀態和 Agent 上下文。支援多語言專案，遵循 OpenSkills 漸進載入原則。

---

前置依賴

二進位制工具

工具	用途
git	克隆、分支、提交、打標籤、推送

環境變數

變數	是否必須	說明
SPEC_DEV_GIT_TOKEN	必須	HTTPS 認證用的個人訪問令牌（PAT）或 OAuth2 Token。用於構造帶認證的克隆 URL 並寫入本地憑據助手。相容 GitHub、GitLab、Bitbucket、Gitea 的 HTTPS 遠端。
SPEC_DEV_GIT_USERNAME	否	寫入 user.name 和憑據 URL 的 Git 使用者名稱。未設定時預設為 oauth2（相容 GitHub/GitLab Token 認證）。
SPEC_DEV_GIT_EMAIL	否	提交時使用的作者郵箱。未設定時預設為 bot@spec-driven-dev。

安全說明 — SPEC_DEV_GIT_TOKEN 僅通過 OpenClaw skills.entries.*.env 機制在執行時注入，絕不寫入任何產物檔案、日誌或迭代摘要。憑據助手使用侷限於當前 Agent 會話的本地 ~/.git-credentials 儲存。

---

快速開始

# 1 – 克隆遠端倉庫並初始化 US 目錄
init-US042
git_remote: https://github.com/my-org/my-repo.git
us_content: |
  ## US042 – OAuth2 登入
  作為使用者，我希望使用 Google 賬號登入。
  ### 驗收標準
  - [ ] Google OAuth2 重定向正常
  - [ ] 回撥後簽發 JWT
context: "Python 3.11 + FastAPI。資料庫為 PostgreSQL 15，不新增依賴。"

# 2 – 鏈式執行各階段（git_remote 在 init 後自動持久化到 current_iter.md）
requirements-US042
architecture-US042
process_design-US042
project_plan-US042
coding-US042
test-US042
bugfix-US042        # 僅當 test 階段報告 HIGH 級失敗時執行
code_review-US042   # 三層門控：commit message + 程式碼質量 + LOGAF Checklist
release-US042       # 僅當 code_review 裁決為 APPROVED 或 APPROVED_WITH_NOTES 時解鎖

---

輸入變數

變數	型別	是否必須	說明
us_id	string	必須	使用者故事 ID（如 US042）。從 <stage>-<us_id> 觸發模式中自動捕獲，對映至所有產物路徑。
stage	enum	必須	生命週期階段：init · requirements · architecture · process_design · project_plan · coding · test · bugfix · code_review · release
git_remote	string	init 階段必須	遠端 Git 倉庫的 HTTPS URL。init 後存入 current_iter.md，後續階段自動讀取，無需重複傳入。
us_content	string	否	使用者故事完整文本。在階段執行前寫入 requirements/US/{us_id}.md。已存在時追加合併，除非 force_overwrite: true。
context	string	否	自由格式的補充上下文，逐字注入到本次產出的每個產物的 ### 補充上下文 標題下。適用於 ADR 摘錄、環境約束、Review 反饋等。
iter_id	string	否	當前迭代 ID（如 iter_003）。省略時自動從 current_iter.md 中檢測；首次執行預設為 iter_001。
force_overwrite	bool	否 · 預設 false	為 true 時覆蓋已有產物檔案，而非追加合併。
skip_skill_scan	bool	否 · 預設 false	為 true 時跳過 available_skills.xml 掃描（適用於 Runner 已在外部完成 Skill 解析的場景）。

---

觸發條件

本 Skill 在以下情況啟用：

1. 階段命令模式 — 使用者輸入 <stage>-<us_id>，例如：

   • init-US042
   • coding-US042
   • code_review-US042
   • release-FEAT_LOGIN

2. Checkpoint 命令 — 任意時刻均可觸發：

   • save_checkpoint-{us_id} 或 checkpoint-{us_id} — 手動儲存當前狀態
   • rollback {ckpt_id} — 回滾到指定 checkpoint
   • rollback {ckpt_id} --git-only — 僅回滾 Git
   • rollback {ckpt_id} --context-only — 僅輸出恢復 Prompt
   • list_checkpoints-{us_id} — 列出所有 checkpoint

3. 下一迭代意圖 — 使用者輸入以下任意一種：

   • {us_id}進行下一個迭代
   • next iteration {us_id}
   • start|begin|run|execute … sprint|iteration|milestone

   → 自動從 requirements/{us_id}/docs/iteration_summary/current_iter.md 恢復上下文繼續執行

---

路徑常量

所有路徑使用 {us_id}、{iter_id}、{version} 作為佔位符。

requirements/US/{us_id}.md
requirements/{us_id}/docs/requirements.md
requirements/{us_id}/docs/architecture.md
requirements/{us_id}/docs/process_design.md
requirements/{us_id}/docs/project_plan.md
requirements/{us_id}/docs/tasks.json
requirements/{us_id}/docs/iteration_summary/current_iter.md
requirements/{us_id}/docs/iteration_summary/{iter_id}.md
requirements/{us_id}/docs/release_notes/{version}.md
requirements/{us_id}/docs/reports/test-{us_id}-report.md
requirements/{us_id}/docs/reports/review-{us_id}-{iter_id}.md
requirements/{us_id}/docs/checkpoints/index.md
requirements/{us_id}/docs/checkpoints/{ckpt_id}.md
auxiliary/coding_standards.md
auxiliary/gitflow_guide.md
auxiliary/skills/available_skills.xml
src/
tests/
config/
CHANGELOG.md
PROJECT_STATUS.md
.github/workflows/ci.yml

---

執行協議

每次呼叫必須按順序執行以下六步協議。

第 0 步 — 發出 stage_start 檢查點

[SKILL:spec-driven-dev] CHECKPOINT stage_start STATUS=OK  us_id={us_id}  stage={stage}

第 1 步 — 驗證輸入

1. 確認 us_id 和 stage 已存在。
2. 若提供了 us_content，寫入（或合併）到 requirements/US/{us_id}.md。
3. 若提供了 context，在記憶體中儲存，並在本次產出的每個產物中以 ### 補充上下文 標題開頭注入。
4. 解析 iter_id：
   • 若顯式提供，直接使用。
   • 否則從 current_iter.md 中讀取。
   • 若檔案不存在，預設為 iter_001。
5. 解析 git_remote：
   • 若顯式提供，使用並持久化到迭代摘要。
   • 否則從 current_iter.md 的 git_remote: 欄位中讀取。
   • 若仍不存在且當前階段不是 init，發出警告後繼續執行。

[SKILL:spec-driven-dev] CHECKPOINT inputs_validated STATUS=OK

第 2 步 — Skill 掃描（skip_skill_scan: true 時跳過）

1. 完整讀取 auxiliary/skills/available_skills.xml。
2. 將可用 Skill 與當前階段需求進行匹配。
3. 若找到匹配項，宣佈：

   "我將呼叫 Skill：<n> 來輔助本次任務。" 隨即完整載入 auxiliary/skills/<n>/SKILL.md 後再繼續執行。

4. 禁止一次性載入所有 Skill — 每次只按需載入一個（漸進披露原則）。

[SKILL:spec-driven-dev] CHECKPOINT skill_scan_done STATUS=OK  skills_loaded=[…]

第 3 步 — 執行階段

嚴格按照下方階段定義章節執行。 每寫完一個強制輸出檔案後發出：

[SKILL:spec-driven-dev] CHECKPOINT artefacts_written STATUS=OK  files=[…]

第 4 步 — 質量門控（僅 coding / test / bugfix 階段）

按語言檢測表執行靜態檢查和測試。

通過時：

[SKILL:spec-driven-dev] CHECKPOINT quality_gate_passed STATUS=OK

失敗時：發出 STATUS=FAIL，彙總失敗資訊，並指示 Agent 進入 bugfix 階段。 同一問題連續失敗 5 次後，停止自動修復並請求人工介入。

第 5 步 — 寫入迭代摘要

1. 遞增 iter_id（如 iter_003 → iter_004）。
2. 使用下方模板寫入 requirements/{us_id}/docs/iteration_summary/{iter_id}.md。
3. 用相同內容覆蓋 requirements/{us_id}/docs/iteration_summary/current_iter.md。
4. 更新 PROJECT_STATUS.md。

[SKILL:spec-driven-dev] CHECKPOINT iteration_summary_written STATUS=OK  iter_id={iter_id}

第 6 步 — 發出 stage_done

[SKILL:spec-driven-dev] CHECKPOINT stage_done STATUS=OK
<stage_done>

---

階段定義

init

目的： 從環境變數配置 Git 憑據、將遠端倉庫克隆到工作區、初始化 US 目錄樹，並將純文本 git_remote URL 記錄到迭代摘要，供後續所有階段免密推拉使用。

讀取： 無（從零啟動）

寫入：

• 克隆後的倉庫（工作區根目錄）
• requirements/US/{us_id}.md（腳手架或來自 us_content）
• 完整的 requirements/{us_id}/docs/ 目錄樹
• requirements/{us_id}/docs/iteration_summary/current_iter.md（存根）
• PROJECT_STATUS.md（初始條目）

憑據配置 — 按此順序執行：

# 1. 從環境變數解析執行時值
GIT_USER="${SPEC_DEV_GIT_USERNAME:-oauth2}"
GIT_EMAIL="${SPEC_DEV_GIT_EMAIL:-bot@spec-driven-dev}"
GIT_TOKEN="${SPEC_DEV_GIT_TOKEN}"        # 必填；metadata.requires.env 已做門控

# 2. 構造帶認證的克隆 URL（Token 內嵌，絕不寫入產物）
#    相容：https://github.com/…  https://gitlab.com/…  https://bitbucket.org/…
REMOTE_HOST=$(echo "${git_remote}" | sed 's|https://||' | cut -d'/' -f1)
CLONE_URL="https://${GIT_USER}:${GIT_TOKEN}@${REMOTE_HOST}/$(echo "${git_remote}" | sed "s|https://${REMOTE_HOST}/||")"

# 3. 克隆
git clone "${CLONE_URL}" .

# 4. 設定提交身份
git config user.name  "${GIT_USER}"
git config user.email "${GIT_EMAIL}"

# 5. 持久化憑據，供本工作區後續 push/pull 靜預設證
git config credential.helper store
printf "https://%s:%s@%s\n" "${GIT_USER}" "${GIT_TOKEN}" "${REMOTE_HOST}" \
  >> ~/.git-credentials
chmod 600 ~/.git-credentials

Token 絕不寫入任何產物或日誌。 僅將不含憑據的裸 git_remote URL 存入 current_iter.md。

關鍵指令：

1. 在任何其他 git 操作前先執行憑據配置程式碼塊。
2. 建立路徑常量中尚不存在的所有子目錄。
3. 若提供了 us_content，寫入 requirements/US/{us_id}.md；否則寫入含佔位標題的 Markdown 腳手架。
4. 若提供了 context，在腳手架中注入 ### 補充上下文 節。
5. 在 current_iter.md 的 git_remote: 欄位中記錄純文本 git_remote URL（不含 Token）。

---

requirements

讀取：

• requirements/US/{us_id}.md
• auxiliary/coding_standards.md

寫入：

• requirements/{us_id}/docs/requirements.md

關鍵指令：

1. 識別功能範圍與邊界。
2. 挖掘非功能性需求（效能、安全、相容性）。
3. 定義可量化的驗收標準。
4. 注入 context 至 ### 補充上下文。

---

architecture

讀取：

• requirements/{us_id}/docs/requirements.md
• auxiliary/coding_standards.md
• auxiliary/gitflow_guide.md

寫入：

• requirements/{us_id}/docs/architecture.md — 必須包含 Mermaid 架構圖

關鍵指令：

1. 選擇架構風格（微服務 / 模組化 / 單體）並說明理由。
2. 定義元件、職責與介面。
3. 說明技術選型決策。
4. 嵌入至少一張 mermaid 架構圖。
5. 注入 context 至 ### 補充上下文。

---

process_design

讀取：

• requirements/{us_id}/docs/architecture.md

寫入：

• requirements/{us_id}/docs/process_design.md — 必須包含 Mermaid 流程圖或狀態圖

關鍵指令：

1. 建模主執行流程（ReAct / Plan-and-Execute / 標準 CRUD，視情況選用）。
2. 詳細描述每個步驟。
3. 定義異常處理與重試/降級行為。
4. 嵌入至少一張 mermaid 流程圖或序列圖。

   小蔥技能7w4.net有更新，你可以訪問看下。

---

project_plan

讀取：

• requirements/{us_id}/docs/architecture.md
• requirements/{us_id}/docs/process_design.md

寫入：

• requirements/{us_id}/docs/project_plan.md
• requirements/{us_id}/docs/tasks.json

關鍵指令：

1. 將工作拆解為粒度 1–3 天的任務，附里程碑、優先順序和工時估算。
2. 按以下 Schema 產出 tasks.json：

   [
    {
      "id": "task-1",
      "name": "任務名稱",
      "scope": "src/module/",
      "stage": "coding",
      "depends_on": []
    }
   ]

---

coding

讀取：

• requirements/{us_id}/docs/iteration_summary/current_iter.md ← 優先讀取
• requirements/{us_id}/docs/architecture.md
• requirements/{us_id}/docs/process_design.md
• requirements/{us_id}/docs/tasks.json
• auxiliary/coding_standards.md
• auxiliary/gitflow_guide.md

寫入：

• src/ 下的原始碼檔案
• tests/ 下的測試檔案

關鍵指令：

1. 優先讀取 current_iter.md 瞭解歷史進度。
2. 只實現當前迭代範圍內的任務。
3. 使用型別註解、清晰命名和詳細 docstring。
4. 遵循語言檢測表對應的工具鏈。
5. 建立並切換到 feature/{task-name} 分支（GitFlow）。
6. 質量門控通過前禁止提交（由 test / bugfix 階段完成）。
7. 將 context 注入相關模組級 docstring。

---

test

讀取：

• src/ 下的原始碼檔案
• auxiliary/coding_standards.md

寫入：

• requirements/{us_id}/docs/reports/test-{us_id}-report.md

關鍵指令：

1. 按語言檢測表執行（或模擬）完整測試套件。
2. 報告：格式化 · Lint · 型別檢查 · 測試結果 · 覆蓋率 %。
3. 覆蓋率目標：整體 ≥ 80%；關鍵模組 ≥ 90%。
4. 每個失敗項輸出：嚴重程度（HIGH / MEDIUM / LOW）及修復建議。
5. 立即修復 HIGH 級失敗；將 MEDIUM / LOW 記錄到 TODO。

---

bugfix

讀取：

• requirements/{us_id}/docs/reports/test-{us_id}-report.md
• 失敗的原始碼 / 測試檔案

寫入：

• src/ 下更新後的原始碼檔案
• tests/ 下更新後的測試檔案
• requirements/{us_id}/docs/reports/test-{us_id}-report.md（追加新條目）

關鍵指令：

1. 針對每個 HIGH 級失敗：分析根因 → 修復 → 驗證。
2. 每批修復後重新執行測試。
3. 所有 HIGH 級失敗解決後，重新執行完整套件。
4. 自動修復上限為 5 次；超限後停止並請求人工介入。
5. 自動 Checkpoint 觸發：同一問題連續失敗 ≥ 3 次時，在第 3 次失敗後立即呼叫 spec-driven-checkpoint：

   invoke_skill: spec-driven-checkpoint
   action: save
   with:
    us_id: "{us_id}"
    iter_id: "{iter_id}"
    stage: "bugfix"
    interrupt_reason: "bugfix_loop_{n}"
    pending_items: "修復失敗的問題列表"

---

code_review

目的（Orchestrator）： 按序呼叫三個獨立子 Agent，依次執行門控一→二→三；收集每個子 Agent 的結構化輸出，合併寫入最終評審報告，並根據聚合裁決決定是否解除 release 進入鎖。

三個子 Agent Skill 須已安裝到 auxiliary/skills/ 並註冊在 available_skills.xml 中：

• cr-commit-check — 門控一：Commit Message 合規校驗
• cr-code-gate — 門控二：程式碼質量靜態門控
• cr-logaf-review — 門控三：LOGAF Checklist 全面評審

讀取：

• requirements/{us_id}/docs/iteration_summary/current_iter.md
• requirements/{us_id}/docs/reports/test-{us_id}-report.md
• auxiliary/skills/available_skills.xml（確認三個子 Agent 已註冊）

寫入：

• requirements/{us_id}/docs/reports/review-{us_id}-{iter_id}.md（彙總評審報告）

---

Orchestrator 執行流程

[SKILL:spec-driven-dev] CHECKPOINT review_start STATUS=OK  us_id={us_id}  iter_id={iter_id}

階段 R-0：收集共享上下文

在呼叫任何子 Agent 之前，統一收集以下資料並快取，按需傳入各子 Agent：

# 1. 獲取 commit log（門控一使用）
GIT_LOG=$(git log main..HEAD --pretty=full)

# 2. 獲取完整 diff（門控二、三使用）
GIT_DIFF=$(git diff main...HEAD)

# 3. 路徑常量
TASKS_PATH="requirements/{us_id}/docs/tasks.json"
ITER_PATH="requirements/{us_id}/docs/iteration_summary/current_iter.md"
TEST_REPORT_PATH="requirements/{us_id}/docs/reports/test-{us_id}-report.md"

---

階段 R-1：呼叫 cr-commit-check（門控一）

invoke_skill: cr-commit-check
with:
  us_id: "{us_id}"
  iter_id: "{iter_id}"
  git_log: $GIT_LOG
  tasks_json_path: $TASKS_PATH

[SKILL:spec-driven-dev] CHECKPOINT review_commit_msg STATUS=<OK|FAIL>

分支邏輯：

• verdict == "FAIL" → 立即終止，跳轉至「彙總報告」步驟，release 被阻塞。
• verdict == "PASS" → 繼續階段 R-2。

---

階段 R-2：呼叫 cr-code-gate（門控二）

invoke_skill: cr-code-gate
with:
  us_id: "{us_id}"
  iter_id: "{iter_id}"
  git_diff: $GIT_DIFF
  iter_summary_path: $ITER_PATH
  coding_standards_path: "auxiliary/coding_standards.md"

快取返回的 findings 供門控三去重使用：

[SKILL:spec-driven-dev] CHECKPOINT review_code_gate STATUS=<OK|WARN|FAIL>

分支邏輯：

• verdict == "FAIL" → 立即終止，跳轉至「彙總報告」步驟，release 被阻塞。
• verdict == "PASS" 或 "WARN" → 繼續階段 R-3，攜帶 findings。

---

階段 R-3：呼叫 cr-logaf-review（門控三）

invoke_skill: cr-logaf-review
with:
  us_id: "{us_id}"
  iter_id: "{iter_id}"
  git_diff: $GIT_DIFF
  us_file_path: "requirements/US/{us_id}.md"
  architecture_path: "requirements/{us_id}/docs/architecture.md"
  test_report_path: $TEST_REPORT_PATH
  code_gate_findings: <門控二返回的 findings 陣列>

[SKILL:spec-driven-dev] CHECKPOINT review_checklist STATUS=<APPROVED|APPROVED_WITH_NOTES|REQUEST_CHANGES>

---

階段 R-4：聚合裁決

最終裁決	觸發條件
REQUEST_CHANGES	門控一 FAIL，或 門控二 FAIL，或 門控三 REQUEST_CHANGES
APPROVED_WITH_NOTES	無 FAIL / REQUEST_CHANGES，但門控二 WARN 或門控三 APPROVED_WITH_NOTES
APPROVED	三層全部 PASS / APPROVED，且無任何 h 級發現

[SKILL:spec-driven-dev] CHECKPOINT review_done STATUS=<APPROVED|APPROVED_WITH_NOTES|REQUEST_CHANGES>

---

彙總評審報告模板

寫入 requirements/{us_id}/docs/reports/review-{us_id}-{iter_id}.md：

# Code Review 報告 – {us_id} / {iter_id}
**日期：** YYYY-MM-DD
**Orchestrator：** spec-driven-dev
**最終裁決：** APPROVED | APPROVED_WITH_NOTES | REQUEST_CHANGES

---

## 門控一：Commit Message 校驗（cr-commit-check）
| 規則 ID | 結果   | 備註 |
|---------|--------|------|
| CM-01   | ✅/❌  |      |
| CM-02   | ✅/❌  |      |
| CM-03   | ✅/❌  |      |
| CM-04   | ✅/❌  |      |
| CM-05   | ✅/❌  |      |
| CM-06   | ✅/❌  |      |

**門控結論：** PASS / FAIL

---

## 門控二：程式碼質量門控（cr-code-gate）
| 發現 ID | LOGAF | 結果  | 檔案:行 | 描述 | 建議 |
|---------|-------|-------|---------|------|------|
| GK-xx   | `h`   | ✅/❌ |         |      |      |

**門控結論：** PASS / WARN / FAIL
**h 級：** N | **m 級：** N | **l 級：** N

---

## 門控三：LOGAF Checklist（cr-logaf-review）
| 發現 ID | LOGAF | 結果  | 檔案:行 | 描述 | 建議 |
|---------|-------|-------|---------|------|------|
| CR-xx   | `m`   | ⚠️    |         |      |      |

**評審結論：** APPROVED / APPROVED_WITH_NOTES / REQUEST_CHANGES
**h 級：** N | **m 級：** N | **l 級：** N

---

## 總結與下一步行動
<!-- REQUEST_CHANGES：列出全部 h 級問題，說明須重走 bugfix→test→code_review -->
<!-- APPROVED_WITH_NOTES：列出 m/l 級建議，可在後續迭代跟進 -->
<!-- APPROVED：解除 release 進入鎖 -->

---

code_review 階段裁決規則

最終裁決	條件	對 release 的影響
APPROVED	三層門控全部 PASS，無任何 h 級問題	✅ 解除 release 進入鎖
APPROVED_WITH_NOTES	無 h 級問題，存在 m/l 級問題已記錄	✅ 解除 release 進入鎖，已知風險已存檔
REQUEST_CHANGES	存在任意 h 級問題（門控二或門控三）	❌ 阻塞 release，必須重走 bugfix→test→code_review。同時自動觸發 checkpoint 儲存：invoke_skill: spec-driven-checkpoint action: save … interrupt_reason: "review_rejected"

---

release

目的： 提交本迭代所有變更、升級版本號、更新變更日誌、寫入發版說明，並將提交與標籤推送至遠端。

讀取：

• 當前工作區（所有質量門控已通過）
• requirements/{us_id}/docs/reports/review-{us_id}-{iter_id}.md ← 必須為 APPROVED 或 APPROVED_WITH_NOTES，否則直接拒絕進入
• CHANGELOG.md
• requirements/{us_id}/docs/iteration_summary/current_iter.md（獲取 git_remote）

寫入：

• main（或配置的基礎分支）上的單次迭代提交
• 更新後的版本宣告檔案（pyproject.toml / package.json / Cargo.toml 等）
• CHANGELOG.md（增量更新）
• requirements/{us_id}/docs/release_notes/{version}.md
• 推送至遠端的 Git 標籤 v{version}

關鍵指令：

1. 前置門控檢查：讀取 review-{us_id}-{iter_id}.md，確認最終裁決為 APPROVED 或 APPROVED_WITH_NOTES。若為 REQUEST_CHANGES 則立即終止，輸出：

   [SKILL:spec-driven-dev] RELEASE BLOCKED — code_review 裁決為 REQUEST_CHANGES，
   請先完成 bugfix → test → code_review 迴圈，清零所有 h 級問題。

2. 確認憑據助手仍處於活動狀態；如會話已重新整理，重新執行 init 憑據配置程式碼塊：

   git config credential.helper   # 應返回 "store"

3. 根據本迭代最高級別的提交型別確定版本升級幅度：

   • feat → minor
   • fix · chore · docs · test · refactor · perf · style · config · build → patch
   • feat! 或 BREAKING CHANGE → major

4. 暫存所有變更並建立單次迭代提交：

   {type}(#{us_id}/{iter_id}): {task_id1}/{desc1}, {task_id2}/{desc2}, …

   允許的 type：feat|fix|config|docs|test|refactor|perf|style|chore|build

5. 按語言執行版本升級命令：

   • Python → cz bump
   • Node → npm version <major|minor|patch>
   • Rust → cargo release <level>
   • Go → git tag v{version}

6. 在 CHANGELOG.md 中追加新版本塊。

7. 將使用者友好的發版說明寫入 requirements/{us_id}/docs/release_notes/v{version}.md。

8. 推送提交和標籤（憑據助手靜默處理認證）：

   git push origin main
   git push origin "v{version}"

---

語言檢測

根目錄檔案	語言	格式化工具	Lint 工具	型別檢查	測試框架
pyproject.toml	Python	black	ruff	mypy	pytest
package.json + tsconfig.json	TypeScript	Prettier	ESLint	tsc	Jest / Vitest
go.mod	Go	gofmt	golangci-lint	—	go test
Cargo.toml	Rust	rustfmt	clippy	—	cargo test
pom.xml	Java	spotless	Checkstyle	SpotBugs	JUnit 5

---

迭代摘要模板

用於每個 {iter_id}.md 和 current_iter.md，目標控制在 800–1500 Token。

# 迭代摘要 – {iter_id}
**日期：** YYYY-MM-DD
**US：** {us_id}
**已完成階段：** {stage}
**git_remote：** https://github.com/org/repo.git
**Code Review 裁決：** APPROVED | APPROVED_WITH_NOTES | REQUEST_CHANGES | 本階段未執行
**呼叫的 Skill：** <逗號分隔列表，或填"無">

## 本次迭代目標
<一段話說明本次迭代要達成什麼。>

## 架構 / 流程變更
<本次迭代做出或修訂的結構性決策。無變化則填"無"。>

## 已完成任務
| 任務 ID | 描述 | 狀態 |
|---------|------|------|
| task-1  | …    | ✅ 完成 |

## 關鍵最佳化點
- …

## 本次釋出版本
<vX.Y.Z 或"本次迭代未釋出">

## 待辦 / 下一步
- …

## 專案狀態快照
<2–3 句話：測試覆蓋率、未解決阻塞項、下一個里程碑。>

注意：git_remote 只儲存純文本 URL — 不含 Token 或任何憑據。

---

響應輸出格式

每次響應必須採用以下結構：

1 · 本次執行計劃

列出本次將完成的步驟。

2 · 可用 Skill 概覽

貼上 auxiliary/skills/available_skills.xml 的完整內容。

3 · Skill 呼叫（如需要）

宣佈並載入匹配 Skill 的 SKILL.md。

4 · 檔案變更清單

每個新建或修改的檔案：完整路徑 + 完整內容（或統一 diff），置於程式碼塊中。

5 · 靜態檢查與測試結果（僅 coding / test / bugfix 階段）

格式化工具、Lint、型別檢查、測試框架的關鍵輸出。

6 · Git 與版本操作

精確的提交資訊、版本升級命令、打標籤命令和推送命令。

7 · 迭代摘要

填寫完整的迭代摘要模板。

8 · 本次發出的進度檢查點

本次執行的每個檢查點及其狀態。

---

禁止行為

• 禁止將 SPEC_DEV_GIT_TOKEN 或任何憑據寫入任何檔案、日誌或產物。
• 禁止一次性載入所有 Skill — 嚴格遵守漸進披露原則。
• 禁止在迭代中途提交；每個完整迭代只允許一次提交。
• 禁止跳過質量門控，即使使用者要求加快速度。
• 禁止跳過 code_review 階段直接進入 release。
• 禁止在 code_review 裁決為 REQUEST_CHANGES 時執行 release；必須先清零所有 h 級問題。
• 禁止將評審反饋中的 m/l 級問題升級為阻塞項，除非使用者明確要求。
• 禁止在路徑常量之外新增或刪除頂層目錄。
• 禁止回溯完整對話歷史；所有上下文只從 current_iter.md 和輸入變數中獲取。
• 禁止在 test 階段存在未解決的 HIGH 級失敗時進入 code_review 階段。

這個 Skill 質量紮實，流程設計完整嚴謹，尤其程式碼評審的三層門控和檢查點恢復機制很實用。文件質量稍顯不足，缺少使用示例；子 Skill 之間的路徑引用存在小 bug；對新手不太友好，命令和概念較多，上手有一定難度。整體推薦給需要規範化開發流程的中大型專案。