開發者撰寫 Spec（高階需求）
       ↓
GSD 自動拆解為 Milestone / Slice / Task
       ↓
每個 Task 的 Dispatch Prompt 自動包含：
  - Task Plan + Must-haves
  - 前置 Task Summary
  - 相關檔案（預載入）
  - 架構決策（DECISIONS.md）
  - 知識庫（KNOWLEDGE.md）

Milestone  →  一個可交付版本（4-10 slices）
  Slice    →  一個可展示的垂直功能（1-7 tasks）
    Task   →  一個 Context Window 大小的工作單元

# .gsd/PREFERENCES.md
reactive_execution: true    # 預設停用

Context 使用率:
  0% ─────── 70% ───── 80% ───── 100%
       正常    │  包裝信號  │  暫停點   │  硬限制
               │           │           │
            自動發送      可選暫停     強制中斷
           包裝提示      檢查點

# .gsd/PREFERENCES.md
context_pause_threshold: 80    # 設為 0 停用（預設）

gsd (CLI binary)
  └─ loader.ts          設定 PI_PACKAGE_DIR、GSD 環境變數，動態載入 cli.ts
      └─ cli.ts         連接 SDK 管理器、載入擴充套件、啟動 InteractiveMode
          ├─ headless.ts       Headless 編排器（CI/cron/腳本）
          ├─ onboarding.ts     首次執行設定精靈
          ├─ wizard.ts         環境填充（auth.json 認證）
          ├─ app-paths.ts      ~/.gsd/agent/、~/.gsd/sessions/、auth.json
          ├─ resource-loader.ts 同步內建擴充套件 + Agent
          └─ src/resources/
              ├─ extensions/gsd/    核心 GSD 擴充（auto、state、commands…）
              ├─ extensions/...     21 個支援擴充
              ├─ agents/            scout、researcher、worker、javascript-pro、typescript-pro
              └─ GSD-WORKFLOW.md    手動引導協議

# .gsd/PREFERENCES.md 中的驗證指令
verification_commands:
  - mvn compile
  - mvn test
  - mvn checkstyle:check

# 前端專案 .gsd/PREFERENCES.md
verification_commands:
  - npm run lint
  - npm run type-check
  - npm run test:unit

# .github/workflows/gsd-auto.yml
name: GSD Auto Build
on:
  workflow_dispatch:
    inputs:
      milestone:
        description: 'Milestone context file'
        required: true

jobs:
  gsd-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '24'

      - name: Install GSD
        run: npm install -g gsd-pi@latest

      - name: Run GSD Headless
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          gsd headless new-milestone \
            --context ${{ inputs.milestone }} \
            --auto \
            --timeout 600000

{
  "mcpServers": {
    "internal-docs": {
      "type": "stdio",
      "command": "/usr/bin/python3",
      "args": ["/opt/mcp/doc-server.py"],
      "env": {
        "API_URL": "http://internal-docs.company.com"
      }
    },
    "code-review": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

# 在 GSD Session 中
mcp_servers                                    # 確認設定檔被載入
mcp_discover(server="internal-docs")           # 確認 Server 啟動並回應
mcp_call(server="internal-docs", tool="search", args={...})  # 測試工具調用

# 1. 安裝 Node.js 24 LTS（若尚未安裝）
winget install OpenJS.NodeJS.LTS

# 2. 驗證 Node.js 版本
node --version   # 應為 v24.x.x

# 3. 全域安裝 GSD-2
npm install -g gsd-pi@latest

# 4. 驗證安裝
gsd --version    # 應顯示 v2.77.x

# 1. 安裝 Node.js 24 LTS
brew install node@24
brew link --overwrite node@24

# 2. 全域安裝 GSD-2
npm install -g gsd-pi@latest

# 3. 驗證安裝
gsd --version

# 1. 安裝 Node.js 24 LTS
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

# 2. 全域安裝 GSD-2
npm install -g gsd-pi@latest

# 3. 驗證安裝
gsd --version

# 1. 安裝 Node.js 24 LTS
curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash -
sudo dnf install -y nodejs git

# 2. 全域安裝 GSD-2
npm install -g gsd-pi@latest

# 3. 驗證安裝
gsd --version

# 1. 安裝 Node.js 與 Git
sudo pacman -S nodejs npm git

# 2. 全域安裝 GSD-2
npm install -g gsd-pi@latest

# 3. 驗證安裝
gsd --version

# 1. 安裝 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc   # 或 ~/.zshrc

# 2. 安裝 Node.js 24 LTS
nvm install 24
nvm use 24

# 3. 全域安裝 GSD-2
npm install -g gsd-pi@latest

# 4. 驗證安裝
gsd --version

# 進入專案目錄
cd /path/to/your-project

# 啟動 GSD（首次會進入設定精靈）
gsd

# 重新執行設定精靈
gsd config

# 檢查 MCP 狀態
gsd
/gsd mcp

# 使用 Claude Code CLI 作為 Provider
gsd
/login
# 選擇 "Claude Code CLI" provider

# 使用 GitHub Copilot 作為 Provider
gsd
/login
# 選擇 "GitHub Copilot" provider
# 依照 OAuth 流程完成認證

# 1. Clone GSD 倉庫
git clone https://github.com/gsd-build/gsd-2.git
cd gsd-2/docker

# 2. 建立 Sandbox
docker sandbox create --template . --name gsd-sandbox

# 3. 進入 Sandbox
docker sandbox exec -it gsd-sandbox bash

# 4. 設定 API Key 並執行
export ANTHROPIC_API_KEY="sk-ant-..."
gsd auto "implement the feature described in issue #42"

# 啟動 Web 介面
gsd --web

# 執行健康檢查
gsd
/gsd doctor

my-enterprise-app/
├── .gsd/                              # GSD 工作目錄（自動產生）
│   ├── PREFERENCES.md                 # 專案級偏好設定
│   ├── PROJECT.md                     # 專案描述（活文件）
│   ├── DECISIONS.md                   # 架構決策記錄（Append-only）
│   ├── KNOWLEDGE.md                   # 跨 Session 知識庫
│   ├── RUNTIME.md                     # 執行環境資訊（API、環境變數、服務）
│   ├── STATE.md                       # 狀態儀表板（自動產生）
│   ├── milestones/
│   │   └── M001-abc123/
│   │       ├── M001-ROADMAP.md        # Milestone 計畫（Slice 清單）
│   │       ├── M001-CONTEXT.md        # 使用者決策
│   │       ├── M001-RESEARCH.md       # 程式碼庫與生態系研究
│   │       ├── slices/
│   │       │   └── S01/
│   │       │       ├── S01-PLAN.md    # Slice 任務拆解
│   │       │       ├── S01-UAT.md     # 人工測試腳本
│   │       │       └── tasks/
│   │       │           ├── T01-PLAN.md    # 任務計畫
│   │       │           ├── T01-SUMMARY.md # 任務摘要
│   │       │           ├── T02-PLAN.md
│   │       │           └── T02-SUMMARY.md
│   │       └── reports/               # HTML 報告
│   ├── metrics.json                   # Token / 成本追蹤
│   ├── auto.lock                      # 崩潰偵測哨兵
│   └── gsd.db                         # SQLite 狀態資料庫
├── AGENTS.md                          # Agent 行為指引（專案級）
├── src/
│   ├── main/java/...                  # Spring Boot 後端
│   └── test/java/...                  # 測試
├── frontend/                          # Vue 前端
├── pom.xml                            # Maven 設定
└── .github/
    └── workflows/                     # CI/CD 設定

# 企業客戶管理平台

## 概述
一個基於 Spring Boot 3.5 + Vue 3 的客戶關係管理系統，
支援多租戶架構、角色權限管理與報表分析。

## 技術棧
- Backend: Java 21, Spring Boot 3.5.x, Clean Architecture
- Frontend: Vue 3.x, TypeScript, Tailwind CSS
- Database: PostgreSQL 16
- Cache: Redis 7
- MQ: Kafka 3.x

## 目前狀態
Milestone M001 — 基礎架構與使用者模組

# 需求規格

## 功能需求
### FR-001: 使用者註冊
- 支援 Email + 密碼註冊
- Email 必須唯一
- 密碼強度驗證（≥ 8 字元、含大小寫和數字）

### FR-002: 使用者登入
- JWT Token 認證
- Token 過期時間 30 分鐘
- 支援 Refresh Token

## 非功能需求
### NFR-001: 效能
- API 回應時間 < 200ms（P95）
- 支援 1,000 併發使用者

### NFR-002: 安全
- OWASP Top 10 防護
- 傳輸層 TLS 1.2+

# 架構決策記錄

## D001: 採用 Clean Architecture
- **日期**: 2026-04-21
- **決策**: 使用 Clean Architecture 分層（Domain → Use Case → Interface → Infrastructure）
- **原因**: 確保業務邏輯與框架解耦，便於測試與維護
- **影響**: 需要額外的介面定義，但長期降低耦合度

## D002: 使用 PostgreSQL 作為主資料庫
- **日期**: 2026-04-21
- **決策**: 開發階段使用 PostgreSQL，正式環境可切換至 Oracle
- **原因**: PostgreSQL 開源免費，語法與 Oracle 相近

# 專案知識庫

## 編碼規範
- Controller 命名：`XxxController`，放在 `adapter.in.web` 套件
- Service 命名：`XxxService`（介面）+ `XxxServiceImpl`（實作）
- Repository 命名：`XxxRepository`，放在 `adapter.out.persistence` 套件

## 已知問題
- Redis 連線池在高併發時需設定 maxTotal >= 50
- Kafka Consumer 需設定 max.poll.records=500 避免 Rebalance

## 最佳做法
- 所有 REST API 回傳統一 ApiResponse 包裝
- 例外處理統一使用 @ControllerAdvice

# 執行環境

## API 端點
- 本地: http://localhost:8080
- SIT: https://sit-api.example.com
- UAT: https://uat-api.example.com

## 環境變數
- SPRING_PROFILES_ACTIVE: dev / sit / uat / prod
- DB_HOST: localhost (dev)
- REDIS_HOST: localhost (dev)

## 服務依賴
- PostgreSQL: localhost:5432
- Redis: localhost:6379
- Kafka: localhost:9092

# Agent 指引

## 程式碼風格
- 使用 Java 21 特性（Records、Pattern Matching、Sealed Classes）
- 遵循 Clean Architecture：Domain 不依賴任何框架
- 每個 public method 必須有 JavaDoc
- 使用 Log4j2 記錄日誌

## 測試要求
- 每個 Service 必須有對應的 JUnit 5 測試
- 測試覆蓋率 > 80%
- 使用 Mockito 模擬外部依賴

## 安全規範
- 不得在程式碼中硬編碼密碼或 API Key
- SQL 查詢必須使用參數化查詢
- 所有 API 端點必須有權限檢查

# 1. 進入專案目錄
cd /path/to/my-enterprise-app

# 2. 確保 Git 已初始化
git init  # 如果尚未初始化

# 3. 建立 AGENTS.md（專案級 Agent 指引）
# 手動撰寫或參考上方範例

# 4. 啟動 GSD
gsd

# 5. GSD 自動偵測到沒有 .gsd/ 目錄，進入討論流程
# → 描述你的專案願景、限制條件與偏好
# → GSD 建立 PROJECT.md 和初始 Milestone

# 6. 設定專案偏好
/gsd prefs

---
version: 1
models:
  research: claude-sonnet-4-6
  planning:
    model: claude-opus-4-7
    fallbacks:
      - openrouter/deepseek/deepseek-r1
  execution: claude-sonnet-4-6
  completion: claude-sonnet-4-6
skill_discovery: suggest
auto_supervisor:
  soft_timeout_minutes: 20
  idle_timeout_minutes: 10
  hard_timeout_minutes: 30
budget_ceiling: 100.00
unique_milestone_ids: true
git:
  isolation: worktree
verification_commands:
  - mvn compile
  - mvn test
  - mvn checkstyle:check
verification_auto_fix: true
verification_max_retries: 2
auto_report: true
---

gsd
# GSD 偵測到新專案，自動進入討論流程
# 描述需求，GSD 會引導你細化 Spec

gsd headless new-milestone --context spec.md --auto

# 使用者管理模組

## 功能需求
1. 使用者註冊（Email + 密碼）
2. 使用者登入（JWT Token）
3. 使用者資料 CRUD
4. 角色權限管理（RBAC）

## 非功能需求
- API 回應時間 < 200ms
- 支援 1000 併發使用者
- 密碼使用 BCrypt 加密
- JWT Token 過期時間 30 分鐘

## 技術限制
- 必須使用 Clean Architecture
- 必須有 80% 以上測試覆蓋率
- 必須通過 OWASP Top 10 安全檢查

Milestone M001: 使用者管理模組
├── Slice S01: 領域模型與基礎架構
│   ├── Task T01: 定義 User Domain Entity 與 Value Objects
│   ├── Task T02: 實作 UserRepository 介面與 JPA 實作
│   └── Task T03: 設定 PostgreSQL 連線與 Flyway Migration
├── Slice S02: 認證與授權
│   ├── Task T01: 實作 RegisterUseCase
│   ├── Task T02: 實作 LoginUseCase（JWT 產生）
│   └── Task T03: 實作 JWT Filter 與 Security Config
├── Slice S03: REST API 端點
│   ├── Task T01: UserController CRUD 端點
│   ├── Task T02: AuthController（Register / Login）
│   └── Task T03: Swagger 文件配置
└── Slice S04: 測試與文件
    ├── Task T01: 單元測試（Service 層）
    ├── Task T02: 整合測試（Controller + Repository）
    └── Task T03: API 文件與 UAT 腳本

# T01-PLAN: 定義 User Domain Entity

## Must-haves

### Truths（可觀察行為）
- [ ] User Entity 包含 id, email, password, name, role 欄位
- [ ] Email 格式驗證通過 Value Object 實作
- [ ] Password 使用 BCrypt 加密

### Artifacts（必須存在的檔案）
- [ ] src/main/java/com/example/domain/model/User.java
- [ ] src/main/java/com/example/domain/model/Email.java
- [ ] src/main/java/com/example/domain/model/Role.java

### Key Links（匯入與連接）
- [ ] User.java 使用 Email Value Object
- [ ] User.java 使用 Role Enum

# Terminal 1 — 自動執行
gsd
/gsd auto

# Terminal 2 — 同步導引（選用）
gsd
/gsd discuss    # 討論架構決策
/gsd status     # 查看進度
/gsd steer      # 修改計畫

靜態檢查（Lint / Compile）
       ↓
指令執行（Unit Test / Integration Test）
       ↓
行為測試（E2E / UAT）
       ↓
人工審查（僅當 Agent 無法自行驗證時）

# .gsd/PREFERENCES.md
verification_commands:
  - mvn compile                    # 編譯檢查
  - mvn test                      # 單元測試
  - mvn checkstyle:check          # 程式碼風格
  - mvn spotbugs:check            # 靜態分析
verification_auto_fix: true        # 失敗時自動修復
verification_max_retries: 2        # 最多重試 2 次

## 新增知識 — 2026-04-21

### Spring Boot 3.5 + JWT 整合
- Spring Security 6.x 不再使用 `WebSecurityConfigurerAdapter`
- 改用 `SecurityFilterChain` Bean 配置
- JWT Filter 必須在 `UsernamePasswordAuthenticationFilter` 之前註冊

### PostgreSQL UUID 主鍵
- 使用 `@GeneratedValue(strategy = GenerationType.UUID)` 而非自定義 Generator
- JPA 3.x 原生支援 UUID 策略

# 登入 Claude Code 作為 Provider
gsd
/login
# 選擇 Claude Code CLI

# 設定模型（建議）
/gsd prefs
# models:
#   planning: claude-opus-4-7
#   execution: claude-sonnet-4-6

# 登入 GitHub Copilot 作為 Provider
gsd
/login
# 選擇 GitHub Copilot
# 完成 OAuth 認證流程

❌ 不好的拆分：
  Task: 實作整個使用者模組（太大）

✅ 好的拆分：
  Task T01: 定義 User Domain Entity 與 Value Objects
  Task T02: 實作 UserRepository 介面
  Task T03: 實作 JPA UserRepositoryImpl
  Task T04: 實作 RegisterUseCase
  Task T05: 實作 UserController

gsd
/gsd auto
# 自動研究 → 規劃 → 執行 → 驗證 → 提交 → 下一輪

gsd
/gsd discuss    # 討論架構決策（決策自動被 Auto Mode 拾取）
/gsd status     # 查看進度儀表板
/gsd steer      # 修改計畫文件（Hard-steer）
/gsd queue      # 排隊下一個 Milestone

gsd
/gsd quick
# 直接描述任務，GSD 以完整保證執行，但跳過規劃開銷

# .gsd/PREFERENCES.md
remote_questions:
  channel: telegram
  channel_id: "your-chat-id"
  timeout_minutes: 15
  poll_interval_seconds: 10

notifications:
  enabled: true
  on_complete: true
  on_error: true
  on_budget: true
  on_milestone: true
  on_attention: true

# Slack 設定
remote_questions:
  channel: slack
  channel_id: "C1234567890"

# Discord 設定
remote_questions:
  channel: discord
  channel_id: "123456789012345678"

# 啟動 Web 介面
gsd --web

gsd
/gsd capture "add rate limiting to API endpoints"

gsd
/gsd visualize

# 自動在 Milestone 完成後顯示視覺化器
# .gsd/PREFERENCES.md
auto_visualize: true

# 專案知識庫

## 架構知識
### Clean Architecture 層級映射
- `domain/model/` → Domain Entities & Value Objects
- `domain/port/` → Input/Output Ports（Use Case 介面）
- `application/service/` → Use Case 實作
- `adapter/in/web/` → REST Controllers
- `adapter/out/persistence/` → JPA Repositories

### Spring Boot 3.5 重要變更
- Security Config 使用 Lambda DSL
- `@SpringBootTest` 預設使用 `MOCK` 環境
- Hibernate 6.x 的 `@Type` 改用 `@JdbcTypeCode`

## 技術陷阱
### PostgreSQL
- JSONB 欄位查詢需使用 `@Query(nativeQuery = true)`
- Sequence 命名需與 Entity 的 `@SequenceGenerator` 一致

### Redis
- Spring Data Redis 的 `@Cacheable` 預設序列化為 JDK 格式
- 建議改用 `Jackson2JsonRedisSerializer`

## 團隊共識
- API 統一使用 `/api/v1/` 前綴
- 所有日期時間使用 ISO 8601 格式
- 錯誤碼格式：`MODULE-XXXX`（例：`USER-0001`）

知識節點類型：
├── 架構決策（Architecture Decision）
├── 技術知識（Technical Knowledge）
├── 已知問題（Known Issue）
├── 最佳做法（Best Practice）
├── 團隊共識（Team Convention）
└── 錯誤教訓（Lesson Learned）

# AGENTS.md

## 領域術語
- **租戶（Tenant）**: 使用系統的企業客戶
- **經辦人（Handler）**: 處理案件的行員
- **核決（Approval）**: 主管審核通過

## 業務規則
- 金額 > 100萬需雙簽核
- 跨行轉帳 T+1 到帳

gsd
/gsd discuss
# 討論架構問題，GSD 自動記錄到 DECISIONS.md
# Auto Mode 會在後續 Task 中參考這些決策

# .gsd/PREFERENCES.md
phases:
  require_slice_discussion: true  # 每個 Slice 前暫停，等待人工討論

# .gsd/PREFERENCES.md
skill_discovery: auto    # auto / suggest / off
always_use_skills:       # 始終載入的技能
  - java-spring-boot
  - clean-architecture

# .gsd/PREFERENCES.md
custom_instructions:
  - "Always use TypeScript strict mode"
  - "Prefer functional patterns over classes"
  - "所有 API 回傳必須包含 correlation-id"

# 快速新增知識條目
/gsd knowledge rule "所有 REST API 必須使用統一回應包裝"
/gsd knowledge pattern "Redis 連線池使用 Lettuce 而非 Jedis"
/gsd knowledge lesson "Flyway Migration 命名必須使用 V{timestamp} 格式"

# .gsd/PREFERENCES.md
skill_discovery: auto       # auto / suggest / off

# 始終載入的技能
always_use_skills:
  - java-spring-boot
  - clean-architecture
  - security-best-practices

# 情境式技能規則
skill_rules:
  - when: "*.java"
    use: java-spring-boot
  - when: "*.vue"
    use: vue-typescript
  - when: "*.sql"
    use: database-design

# 設定技能過期天數
skill_staleness_days: 60    # 60 天未使用的技能降低優先級
                            # 設為 0 停用此功能

gsd
/gsd doctor

# 查看日誌
/gsd logs
# 瀏覽 Activity、Debug、Metrics 日誌

# 客戶管理系統 — Spec

## 系統目標
建立一個客戶關係管理（CRM）系統，支援客戶 CRUD、搜尋與分頁。

## 後端需求
- Spring Boot 3.5.x + Java 21
- Clean Architecture（Domain → Application → Infrastructure → Interface）
- PostgreSQL 資料庫
- RESTful API + Swagger UI
- JWT 認證
- 分頁與排序支援

## 前端需求
- Vue 3 + TypeScript + Tailwind CSS
- 客戶列表（分頁、搜尋）
- 客戶詳情頁
- 新增/編輯客戶表單
- 登入頁面

## API 端點
- POST /api/v1/auth/login
- POST /api/v1/auth/register
- GET /api/v1/customers?page=0&size=20&search=keyword
- GET /api/v1/customers/{id}
- POST /api/v1/customers
- PUT /api/v1/customers/{id}
- DELETE /api/v1/customers/{id}

## 資料模型
### Customer
- id: UUID
- name: String (required, max 100)
- email: String (required, unique)
- phone: String (optional)
- address: String (optional)
- status: ACTIVE / INACTIVE
- createdAt: Timestamp
- updatedAt: Timestamp

## 安全要求
- 密碼 BCrypt 加密
- SQL Injection 防護（參數化查詢）
- XSS 防護（輸入驗證）
- JWT Token 30 分鐘過期

# 建立專案目錄
mkdir crm-system && cd crm-system
git init

# 建立 AGENTS.md
cat > AGENTS.md << 'EOF'
# Agent 指引

## 後端規範
- Java 21，使用 Records、Sealed Classes
- Clean Architecture 四層：domain / application / adapter.in / adapter.out
- 每個 public method 必須有 JavaDoc
- 使用 Log4j2
- 測試覆蓋率 > 80%

## 前端規範
- Vue 3 Composition API + TypeScript
- 元件命名使用 PascalCase
- 使用 Pinia 狀態管理
- 使用 Axios HTTP Client

## 安全規範
- 不得硬編碼敏感資訊
- 所有 API 必須有權限檢查
- 輸入驗證使用 Bean Validation
EOF

# 啟動 GSD
gsd

# 登入 Provider
/login
# 選擇 Anthropic，貼上 API Key

# 開始新 Milestone（提供 Spec）

Milestone M001-crm001: 客戶管理系統 MVP

├── Slice S01: 專案骨架與領域模型（風險：低）
│   ├── T01: Spring Boot 專案初始化 + Maven 依賴
│   ├── T02: Clean Architecture 套件結構
│   ├── T03: Customer Domain Entity + Value Objects
│   └── T04: 資料庫 Migration（Flyway）
│
├── Slice S02: 後端 CRUD API（風險：中）
│   ├── T01: CustomerRepository 介面 + JPA 實作
│   ├── T02: CRUD Use Cases（Create / Read / Update / Delete）
│   ├── T03: CustomerController + Swagger
│   └── T04: 分頁與搜尋實作
│
├── Slice S03: 認證與授權（風險：高）
│   ├── T01: User Entity + Repository
│   ├── T02: JWT 工具類
│   ├── T03: Spring Security Config
│   └── T04: AuthController（Login / Register）
│
├── Slice S04: Vue 前端（風險：中）
│   ├── T01: Vue 專案初始化 + Router + Pinia
│   ├── T02: 登入頁 + Auth Store
│   ├── T03: 客戶列表頁（分頁 + 搜尋）
│   └── T04: 客戶詳情與表單頁
│
└── Slice S05: 測試與整合（風險：低）
    ├── T01: 後端單元測試
    ├── T02: 後端整合測試
    └── T03: API 文件完善 + UAT 腳本

# Terminal 1 — 開始自動執行
/gsd auto

# GSD 開始自動工作：
# → Research: 偵察專案結構，研究 Spring Boot 3.5 最新 API
# → Plan S01: 拆解第一個 Slice 的 Tasks
# → Execute T01: 初始化 Spring Boot 專案
# → Verify: mvn compile ✓
# → Execute T02: 建立套件結構
# → Verify: mvn compile ✓
# → ...（持續推進）

# Terminal 2 — 監控進度
/gsd status

# 輸出範例：
# ┌─────────────────────────────────────────┐
# │ M001-crm001: 客戶管理系統 MVP          │
# │ Progress: ████████░░ 40%               │
# │ Current: S02/T03 - CustomerController   │
# │ Cost: $2.34 / Budget: $100.00          │
# │ Elapsed: 1h 23m                         │
# └─────────────────────────────────────────┘

package com.example.crm.domain.model;

import java.time.Instant;
import java.util.UUID;

/**
 * 客戶領域實體。
 * 
 * <p>代表系統中的一個客戶，包含基本資訊與狀態管理。
 * 遵循 DDD 原則，業務邏輯封裝在實體內部。</p>
 */
public class Customer {

    private final UUID id;
    private String name;
    private Email email;
    private String phone;
    private String address;
    private CustomerStatus status;
    private final Instant createdAt;
    private Instant updatedAt;

    /**
     * 建立新客戶。
     *
     * @param name  客戶名稱（必填）
     * @param email 客戶信箱（必填，唯一）
     * @return 新建的客戶實體
     */
    public static Customer create(String name, Email email) {
        return new Customer(
            UUID.randomUUID(),
            name,
            email,
            null,
            null,
            CustomerStatus.ACTIVE,
            Instant.now(),
            Instant.now()
        );
    }

    /**
     * 停用此客戶。
     */
    public void deactivate() {
        this.status = CustomerStatus.INACTIVE;
        this.updatedAt = Instant.now();
    }

    // Constructor, getters...
}

package com.example.crm.application.service;

import com.example.crm.domain.model.Customer;
import com.example.crm.domain.model.Email;
import com.example.crm.domain.port.out.CustomerRepository;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

/**
 * 建立客戶使用案例。
 */
public class CreateCustomerUseCase {

    private static final Logger log = LogManager.getLogger(CreateCustomerUseCase.class);
    private final CustomerRepository customerRepository;

    public CreateCustomerUseCase(CustomerRepository customerRepository) {
        this.customerRepository = customerRepository;
    }

    /**
     * 執行建立客戶。
     *
     * @param command 建立客戶命令
     * @return 新建的客戶
     * @throws EmailAlreadyExistsException 當信箱已存在時
     */
    public Customer execute(CreateCustomerCommand command) {
        log.info("建立客戶: {}", command.name());

        Email email = Email.of(command.email());

        if (customerRepository.existsByEmail(email)) {
            throw new EmailAlreadyExistsException(email.value());
        }

        Customer customer = Customer.create(command.name(), email);
        return customerRepository.save(customer);
    }

    public record CreateCustomerCommand(String name, String email) {}
}

## 2026-04-21 新增

### Spring Boot 3.5 + Clean Architecture
- `@Repository` 註解放在 Adapter 層的 JPA 實作上，不放在 Port 介面
- Use Case 不應直接依賴 Spring 註解，保持領域純淨
- DTO ↔ Entity 轉換使用 Mapper 類，不在 Controller 直接操作 Entity

### Vue 3 + Pinia
- `defineStore` 建議使用 Setup Store 語法（Composition API 風格）
- Axios interceptor 統一處理 401 → 導向登入頁

# 手動產生報告
/gsd export --html

# 報告位置：.gsd/reports/
# 包含：專案摘要、進度樹、Slice 依賴圖、成本/Token 指標、執行時間線

# AGENTS.md — 安全規範

## 必須遵守
- 所有 SQL 使用參數化查詢（PreparedStatement 或 JPA）
- 密碼使用 BCrypt（cost factor ≥ 12）加密
- 不得在日誌中輸出敏感資訊（密碼、API Key、Token）
- 所有 API 輸入必須驗證（使用 Bean Validation @Valid）
- CORS 設定必須明確指定允許的 Origin（禁止 *）
- JWT Token 必須設定過期時間（≤ 30 分鐘）
- 檔案上傳必須驗證副檔名和 MIME Type

## 禁止事項
- 禁止使用 eval() 或動態程式碼執行
- 禁止在前端儲存敏感資料（localStorage 存 JWT 除外）
- 禁止使用 MD5 / SHA-1 作為密碼雜湊
- 禁止關閉 CSRF 保護（除非 API-only 應用）
- 禁止在程式碼中硬編碼任何認證資訊

# .gsd/PREFERENCES.md
verification_commands:
  - mvn compile
  - mvn test
  - mvn checkstyle:check
  - mvn spotbugs:check           # 靜態分析（含安全規則）
  - mvn org.owasp:dependency-check-maven:check  # 依賴漏洞掃描

<plugin>
    <groupId>com.github.spotbugs</groupId>
    <artifactId>spotbugs-maven-plugin</artifactId>
    <version>4.8.6.6</version>
    <configuration>
        <plugins>
            <plugin>
                <groupId>com.h3xstream.findsecbugs</groupId>
                <artifactId>findsecbugs-plugin</artifactId>
                <version>1.13.0</version>
            </plugin>
        </plugins>
    </configuration>
</plugin>

<!-- pom.xml -->
<plugin>
    <groupId>org.owasp</groupId>
    <artifactId>dependency-check-maven</artifactId>
    <version>10.0.4</version>
    <configuration>
        <failBuildOnCVSS>7</failBuildOnCVSS>
        <suppressionFiles>
            <suppressionFile>dependency-check-suppressions.xml</suppressionFile>
        </suppressionFiles>
    </configuration>
</plugin>

## API 安全規範
- 所有 API 端點必須有認證（除了 /api/v1/auth/**）
- 使用 @PreAuthorize 進行方法級權限控制
- Rate Limiting：每個 IP 每分鐘最多 60 次請求
- 回應不得洩漏技術細節（關閉 Spring Boot 預設錯誤頁面）
- 所有 API 回應必須設定安全標頭：
  - X-Content-Type-Options: nosniff
  - X-Frame-Options: DENY
  - X-XSS-Protection: 1; mode=block
  - Strict-Transport-Security: max-age=31536000

# .github/workflows/security-scan.yml
name: Security Scan
on: [push, pull_request]

jobs:
  sast:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: SAST Scan (SpotBugs + FindSecBugs)
        run: mvn spotbugs:check

  sca:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Dependency Check
        run: mvn org.owasp:dependency-check-maven:check

  sonarqube:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: SonarQube Scan
        run: |
          mvn sonar:sonar \
            -Dsonar.host.url=${{ secrets.SONAR_HOST }} \
            -Dsonar.token=${{ secrets.SONAR_TOKEN }}

# 安全知識庫

## OWASP Top 10 防護
### A01: Broken Access Control
- 使用 Spring Security Method Security（@PreAuthorize）
- 資源存取必須驗證 ownership

### A02: Cryptographic Failures
- 使用 BCrypt（cost ≥ 12）
- 傳輸層必須使用 TLS 1.2+
- 敏感資料加密存儲

### A03: Injection
- JPA 參數化查詢（永不拼接 SQL）
- Input Validation（@Valid + Custom Validator）

### A07: Security Misconfiguration
- 關閉 Spring Boot Actuator 的敏感端點
- 正式環境禁止開啟 debug 模式

# 方式 1：互動式討論
gsd
/gsd discuss
# 描述需求變更，GSD 自動更新 DECISIONS.md
# 變更在下一個 Phase 邊界被 Auto Mode 拾取

# 方式 2：Hard-steer（直接修改計畫）
/gsd steer
# 直接編輯 Roadmap 或 Slice Plan 文件

# 方式 3：重新思考
/gsd rethink
# 啟動對話式專案重組

gsd
/gsd quick
# 描述 Bug 和期望行為
# GSD 以完整保證執行，但跳過規劃開銷

gsd
/gsd start bugfix
# 使用內建的 bugfix 工作流範本
# 自動建立修復分支、執行修復、驗證、合併

gsd
/gsd forensics
# 完整存取 GSD 除錯器
# 檢視 dispatch 決策、狀態轉換、計時數據

# 查看日誌
/gsd logs
# 瀏覽三種日誌：
# - Activity Log: 使用者活動
# - Debug Log: 除錯資訊
# - Metrics Log: 效能指標

# 審查知識庫
cat .gsd/KNOWLEDGE.md

# 移除過時知識
# 補充新的最佳做法
# 更新技術限制

---
status: completed
duration_minutes: 8
tokens_used: 45000
cost_usd: 0.18
model: claude-sonnet-4-6
---

## 完成摘要
成功實作 CustomerController CRUD 端點。

## 教訓
- Spring Boot 3.5 的 `@RequestBody` 預設使用 Jackson 的 `@JsonNaming(SnakeCaseStrategy)`
- 分頁使用 `Pageable` 時，需在 Repository 方法上明確指定 Sort

## 待改善
- 缺少 Swagger 文件的詳細範例

# .gsd/PREFERENCES.md
phases:
  require_slice_discussion: true

# 在 Auto Mode 執行期間，另一個終端討論
gsd
/gsd discuss
# 討論內容自動寫入 DECISIONS.md
# Auto Mode 在下一個 Phase 邊界拾取

# Headless Mode 配合自動重啟
gsd headless auto --max-restarts 5

# 歸檔已完成 Milestone 的 Phase 目錄
/gsd cleanup

# 查看 Milestone 報告
/gsd export --html

# 更新 GSD 到最新版本
npm update -g gsd-pi

# 或指定版本
npm install -g gsd-pi@2.77.0

# 在 GSD 內部更新
gsd update

# 驗證版本
gsd --version

# 在專案目錄中
gsd
/gsd migrate

# 或指定路徑
/gsd migrate ~/projects/my-old-project

# AGENTS.md 版本管理建議

## 版本紀錄
- 2026-04-01: 初始版本，Java 21 + Spring Boot 3.5
- 2026-04-15: 新增 PostgreSQL JSONB 規範
- 2026-04-21: 更新 Security Config 為 Lambda DSL

# 檢查是否有 deprecated 的設定
# 舊：agent-instructions.md（已廢棄）
# 新：AGENTS.md 或 CLAUDE.md

# .gsd/PREFERENCES.md
token_profile: balanced    # budget / balanced / quality

# budget:   省 40-60%，跳過研究/重評估，最少 Context
# balanced: 省 10-20%，跳過 Slice 研究，標準 Context
# quality:  不省，全 Phase 全 Context

simple（文件任務）→ 快速模型（如 Haiku）
standard（一般開發）→ 標準模型（如 Sonnet）
complex（架構設計）→ 強力模型（如 Opus）

budget_ceiling: 100.00    # USD 上限

models:
  research: openrouter/deepseek/deepseek-r1    # 便宜但夠用
  planning:
    model: claude-opus-4-7                      # 最強模型做規劃
    fallbacks:
      - openrouter/z-ai/glm-5                  # Fallback
  execution: claude-sonnet-4-6                  # 平衡的執行模型
  completion: claude-sonnet-4-6                 # 快速完成

# 多個 Worker 同時執行不同 Milestone
# 使用 .gsd/parallel/ 協調

# Terminal 1
gsd --worktree
/gsd auto  # Milestone A

# Terminal 2
gsd --worktree
/gsd auto  # Milestone B

# .gsd/PREFERENCES.md
git:
  isolation: worktree    # none / worktree / branch

gsd
/gsd queue
# 在 Auto Mode 運行期間，安全地排隊下一個 Milestone

# 使用內建工作流範本
/gsd start bugfix      # Bug 修復流程
/gsd start release     # 發佈流程

# 查看可用範本
/gsd workflow list

# 安裝自訂範本
/gsd workflow install my-workflow.md

# 查看成本報告
/gsd status

# Dashboard 顯示：
# - 每單元 Token 使用量與成本
# - 按 Phase / Slice / Model 分類
# - 成本預測（基於已完成工作）
# - 預算使用率

# .gsd/PREFERENCES.md
budget_ceiling: 50.00              # USD 上限
token_profile: balanced             # Token 優化策略
budget_enforcement: pause           # warn | pause | halt
auto_supervisor:
  hard_timeout_minutes: 30          # 單任務最長時間
show_token_cost: true               # 即時顯示 Token 成本
service_tier: default               # default | flex（低優先低價）

gsd
/gsd fast          # 切換 service_tier: flex（較低價格但可能較慢）

# .gsd/PREFERENCES.md
post_unit_hooks:
  - name: "generate-changelog"
    after: "code"              # code | test | doc | any
    prompt: "根據最近修改生成 CHANGELOG.md 更新條目"
    model: "claude-sonnet-4-6"
    max_cycles: 3
    artifact: "changelog.md"
    retry_on: "no changes"
    agent: "worker"
    enabled: true
  
  - name: "api-doc-sync"
    after: "code"
    prompt: "確保 OpenAPI spec 與實作一致"
    model: "claude-sonnet-4-6"
    max_cycles: 2
    agent: "worker"
    enabled: true

# .gsd/PREFERENCES.md
pre_dispatch_hooks:
  - name: "security-gate"
    condition: "unit.type == 'code'"
    action: modify              # modify | skip | replace
    prompt: "在單元指令前加入安全掃描要求"
    enabled: true

  - name: "skip-docs-on-hotfix"
    condition: "branch.startsWith('hotfix/') && unit.type == 'doc'"
    action: skip
    enabled: true

# .gsd/PREFERENCES.md
hooks:
  pre_unit:
    - command: "npm run lint:fix"
      on_fail: warn            # warn | abort
  post_unit:
    - command: "npm test"
      on_fail: abort

# .gsd/PREFERENCES.md
reactive_execution: true
parallel:
  max_concurrent: 3
  strategy: dependency-aware   # dependency-aware | sequential

Slice: "新增使用者管理 API"
├─ Task A: 建立 Entity 類別         ← 無依賴，立即執行
├─ Task B: 建立 Repository 介面      ← 依賴 A
├─ Task C: 建立 Service 層           ← 依賴 B
├─ Task D: 建立 Controller           ← 依賴 C
├─ Task E: 建立資料庫 Migration      ← 依賴 A，與 B/C/D 平行
└─ Task F: 建立整合測試              ← 依賴 C + D

# .gsd/PREFERENCES.md（企業範本）
provider: anthropic
model: claude-sonnet-4-6
planning_model: claude-opus-4-7
auto_mode:
  iterations: 10
  cost_limit: 3.00
  budget_enforcement: pause
git:
  isolation: worktree
  auto_push: true
  push_branches: auto
  snapshots: true
  auto_pr: true
  pr_target_branch: develop
  merge_strategy: squash
skill_discovery: suggest
custom_instructions:
  - "所有 API 端點必須包含 OpenAPI 註解"
  - "程式碼必須符合 SonarQube Quality Gate"
  - "日誌必須使用結構化格式（JSON）"
  - "資料庫操作必須在 Transaction 內完成"
context_management:
  observation_masking: true
  compaction_threshold: 30000
notifications:
  enabled: true
  on_complete: true
  on_error: true
  on_budget: true
remote_questions:
  channel: telegram
  channel_id: "your-chat-id"

# 1. 豐富 AGENTS.md
# 加入具體的技術規範和禁止事項

# 2. 使用 /gsd steer 修正計畫
/gsd steer
# 直接修改 Slice Plan 或 Task Plan

# 3. 使用 /gsd discuss 提供額外指引
/gsd discuss
# 討論具體期望，決策記錄到 DECISIONS.md

# 4. 啟用 Slice Discussion
# .gsd/PREFERENCES.md
# phases:
#   require_slice_discussion: true

# 1. 使用 Token 優化
token_profile: budget    # 省 40-60%

# 2. 使用 Complexity Routing
# 簡單任務自動用便宜模型

# 3. 拆分 Task
# 確保每個 Task 在一個 Context Window 內完成

# 4. 減少 Context 注入
# 精簡 KNOWLEDGE.md，只保留相關知識

# 1. 按 Escape 暫停
# 檢查當前狀態

# 2. 查看 Forensics
/gsd forensics

# 3. 手動推進
/gsd next
# 以 Step Mode 手動推進一步

# 4. 檢查健康度
/gsd doctor

# GSD 自動恢復
gsd
/gsd auto
# 讀取 auto.lock，合成恢復簡報，從中斷點繼續

# 恢復特定 Session
gsd sessions
# 互動式 Session 選擇器

# 恢復最近的 Session
gsd --continue
# 或
gsd -c

# .gsd/PREFERENCES.md
unique_milestone_ids: true
# Milestone 名稱會附加 6 字元隨機字串
# 例如：M001-ush8s3（而非 M001）

# 設定 Proxy
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# 使用 API Key（避免 OAuth）
gsd config
# 選擇 API Key 認證方式

# 組織級預算控制
# 每個專案 .gsd/PREFERENCES.md
budget_ceiling: 50.00        # 每 Milestone 預算上限
token_profile: balanced       # Token 優化策略

# 每週產出成本報告
/gsd status > weekly-cost-report.md

# 使用 Headless Query 自動收集
gsd headless query
# 回傳 JSON：phase、next dispatch、成本

# 強制驗證（不可跳過）
verification_commands:
  - mvn compile
  - mvn test
  - mvn checkstyle:check
  - mvn spotbugs:check
verification_auto_fix: true
verification_max_retries: 2

# 團隊 Git 設定
git:
  isolation: worktree          # Worktree 隔離
  manage_gitignore: true       # GSD 管理 .gitignore

unique_milestone_ids: true     # 避免 Milestone ID 衝突

# ── GSD: Runtime / Ephemeral（每人每 Session）──
.gsd/auto.lock
.gsd/completed-units*.json
.gsd/state-manifest.json
.gsd/STATE.md
.gsd/metrics.json
.gsd/activity/
.gsd/runtime/
.gsd/worktrees/
.gsd/parallel/
.gsd/gsd.db*
.gsd/journal/
.gsd/doctor-history.jsonl
.gsd/event-log.jsonl
.gsd/reports/
.gsd/milestones/**/continue.md
.gsd/milestones/**/*-CONTINUE.md

# ── GSD: 納入版控的檔案 ──
# .gsd/PREFERENCES.md    → 團隊共享設定
# .gsd/PROJECT.md         → 專案描述
# .gsd/DECISIONS.md       → 架構決策
# .gsd/KNOWLEDGE.md       → 知識庫
# .gsd/RUNTIME.md         → 執行環境
# .gsd/milestones/        → Milestone 計畫與成果

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

{
  "mcpServers": {
    "remote-api": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

gsd
/gsd mcp
# 顯示所有已連線的 MCP Server 及可用工具

# 或在 Doctor 中檢查
/gsd doctor
# MCP 區段會顯示連線狀態

gsd
/gsd prefs import-claude
# 自動偵測並匯入 claude_desktop_config.json 中的 MCP 設定

dynamic_routing:
  enabled: true
  rules:
    - condition: "task.complexity == 'low'"
      model: "claude-haiku-4"
    - condition: "task.complexity == 'medium'"
      model: "claude-sonnet-4-6"
    - condition: "task.complexity == 'high'"
      model: "claude-opus-4-7"
    - condition: "task.type == 'test'"
      model: "claude-sonnet-4-6"

notifications:
  enabled: true
  on_complete: true      # Milestone 完成時通知
  on_error: true         # 錯誤發生時通知
  on_budget: true        # 接近預算上限時通知
  on_milestone: true     # 里程碑狀態變更時通知
  on_attention: true     # 需要人工注意時通知

context_management:
  observation_masking: true     # 遮蔽冗長工具觀察結果
  compaction_threshold: 30000   # Token 超過此閾值時觸發壓縮

context_pause_threshold: 0.8    # Context 壓力 80% 時暫停

git:
  isolation: worktree          # none | worktree | branch
  auto_push: true              # 單元完成後自動 push
  push_branches: auto          # auto | always | never
  snapshots: true              # 每個單元完成後建立快照
  pre_merge_check: true        # Merge 前執行驗證指令
  commit_type: conventional    # conventional | descriptive | minimal
  main_branch: main            # 主分支名稱
  merge_strategy: squash       # squash | merge | rebase
  commit_docs: true            # 在 commit message 中附加文件
  auto_pr: true                # Milestone 完成後自動建立 PR
  pr_target_branch: develop    # PR 目標分支
  worktree_post_create: ""     # Worktree 建立後執行的命令
  manage_gitignore: true       # GSD 自動管理 .gitignore

github:
  sync: true                   # 啟用 GitHub 同步
  auto_issue: true             # 自動建立 Issue
  auto_pr: true                # 自動建立 PR
  labels:
    - "gsd-auto"
    - "ai-generated"

forensics_dedup: true          # 去重重複的 Forensics 記錄
show_token_cost: true          # 即時顯示每個 API 呼叫的成本
auto_visualize: true           # Milestone 完成後自動開啟視覺化器

parallel:
  max_concurrent: 3            # 最大同時執行的任務數
  strategy: dependency-aware   # dependency-aware | sequential
  conflict_resolution: serialize  # serialize | abort

service_tier: default          # default | flex（低優先低價）
unique_milestone_ids: true     # Milestone ID 附加隨機後綴
auto_supervisor:
  hard_timeout_minutes: 30     # 單任務最長執行時間
skill_discovery: suggest       # auto | suggest | off
always_use_skills:             # 始終載入的技能
  - java-spring-boot
fetchAllowedUrls:              # 允許存取的 URL Pattern
  - "https://docs.company.com/*"
  - "https://api.company.com/*"