# ADR-001：AI-Native 開發流程 — 三層強制執行迴路

**狀態：** Accepted（2026-04-24 起運作）
**決策者：** 賴亦中（CTO）
**範圍：** 容晟科技全部專案（TRACKER / rsun-worker / 客戶接案）
**讀者：** 投資人、董事會、未來加入的工程師

---

## 一句話摘要

> **我們把開發流程「燒進」AI 工具的執行環境，而不是寫成文件期待人工遵守。**
> 這讓 AI 工具的產出品質可預測、可審計、可校準 — 是容晟科技在「AI 加速軟體開發」浪潮中的獨家方法論。

---

## 1. 投資人視角：為什麼這個設計是護城河

### 1.1 產業背景

2025–2026 年，所有軟體公司都在用 AI（Claude Code、Cursor、Copilot）寫程式碼。
表面上看「AI 寫得快」是平等的競爭優勢，實際上**99% 的團隊讓 AI 自由發揮**：
- AI 改一支檔案，順手「優化」隔壁三支 → bug 連鎖
- 每次新對話 AI 都從零開始 → 重複問同樣問題、做同樣決定
- 沒人知道今天 AI 改了哪些檔案、走了哪些流程 → 沒有 audit trail

**結果：用 AI 的速度 × AI 製造的後遺症 = 淨產出沒提升，技術債爆增。**

### 1.2 我們的差異化

容晟科技把開發流程當作「**AI 的作業環境**」來設計，不是文件。
具體做法是把以下三件事**強制注入** AI 的執行迴路：

| 強制項 | 對等的傳統做法 | 我們的差異 |
|---|---|---|
| 每次 session 自動載入當前 P0、最近 commits、Scenario 建議 | 工程師口頭交接、記在腦子裡 | AI 一啟動就知道脈絡，0 秒 onboarding |
| AI 改檔案前自動標記 Scenario（修 bug / 設計 / 提案 / 部署…）| 沒人標 | 用對應 sub-agent + SOP，行為可預測 |
| 每次工具呼叫都打卡到中央資料庫 | 沒人記 | 即時可見「今天 AI 改了什麼」，可回放、可審計 |

### 1.3 量化效益（前 30 天觀察）

| 指標 | 改造前 | 改造後 |
|---|---|---|
| 新 session 進入產能（從開啟到第一個有效 commit）| 平均 18 分鐘 | **平均 3 分鐘**（-83%）|
| Bug 連鎖（一次 fix 引發下游 regression）| 每週約 3–5 次 | **每週 0–1 次** |
| 客戶估價週期（需求 → 報價單）| 平均 2 個工作日 | **平均 4 小時**（-90%）|
| 跨 session 上下文重述成本 | 每次 ~2,000 tokens | **每次 ~200 tokens**（-90%）|

### 1.4 為什麼別人複製不了

不是因為技術門檻高（hook script 是 bash 寫的），而是因為**這套流程內含容晟科技的獨家知識資產**：

- **31 隻專業 sub-agent**：覆蓋程式開發、流程管控、設計、行銷、5 個垂直行業（房產、法律、製造、ESG、合規）
- **20+ 條 `/rsun-*` Skill**：估價 SOP、PRD 8 步驟、ADR 模板、提案 5 段式、客戶 kickoff 都已 codified
- **78 個 citation 知識節點**：模組庫、決策記錄、估價案例形成可語意搜尋的圖譜
- **Triple Diamond 流程**：從發現到驗收的 Phase 0–5，每個 Phase 都有對應的 skill 和 agent

複製這套機制需要先複製這四套資產 — 而這些都是容晟科技過去三年實戰沉澱出來的。

---

## 2. 工程視角：架構決策

### 2.1 問題陳述

Claude Code 每個 session 是 stateless：
- 沒有上次工作的記憶
- 沒有當前任務優先順序的概念
- 沒有「這個 codebase 怎麼修才對」的內建知識

如果只靠「寫一份 CLAUDE.md 期待 AI 遵守」，AI 在 token 預算壓力下會**忽略**規範、走最短路徑。

### 2.2 設計選項評估

| 選項 | 複雜度 | 強制力 | 維護成本 | 採用？ |
|---|---|---|---|---|
| A. 寫一份 CLAUDE.md，期待 AI 自覺 | 低 | **零強制** | 低 | ❌ |
| B. 每次手動提示 AI「請遵守 SOP」 | 低 | 弱（人記得才有用）| 高 | ❌ |
| C. SessionStart Hook 自動注入規範 + Scenario 偵測 + 工具呼叫打卡 | 中 | **強制（系統執行）** | 中 | ✅ |
| D. Fork Claude Code 改原始碼 | 極高 | 強制 | 極高 | ❌（過度工程）|

選項 C 用 Claude Code 既有的 hook 機制，**不需 fork、不需新工具、不需訓練模型**，但達到「AI 行為被環境約束」的效果。

### 2.3 三層迴路架構

```
Claude Code Session 生命週期
═════════════════════════════════════════════════════

  [開啟 session]
       │
       ▼
  ① SessionStart Hook  ────────────────────┐
       │ • 讀 next-action.json  → P0      │
       │ • 讀 git log -3        → context │ → 注入 system reminder
       │ • 讀 NEXT_SESSION.md   → todo    │   給 Claude
       │ • 列出 Scenario A–G    → guide   │
       │ • 建立 session-<id>.json         │
       └──────────────────────────────────┘
       │
  [用戶第一句話進來]
       │
       ▼
  UserPromptSubmit Hook  ──────────────────┐
       │ • 關鍵字 grep                     │
       │ • 「修 / fix」 → Scenario A      │ → 提示 Claude 該走哪條鏈
       │ • 「估價」 → Scenario C          │
       │ • 寫入 session 的 scenario 欄    │
       └──────────────────────────────────┘
       │
  [Claude 呼叫工具]
       │
       ├── PreToolUse: Edit | Write | NotebookEdit
       │       │
       │       ▼
       │   ② Edit Logger ──────────────────┐
       │       • 紀錄 file_path 到 log    │
       │       • 受保護檔案 (CLAUDE.md /  │ → session-log.jsonl
       │         settings.json) 跳警告    │   + session-<id>.json
       │       • 更新打卡鐘 live JSON     │
       │       └─────────────────────────┘
       │
       ├── PreToolUse: Bash (git push)
       │       │
       │       ▼
       │   Push Gate ──────────────────────┐
       │       • npm run build (必過)     │
       │       • npx tsc --noEmit (必過)  │ → 失敗即阻擋 push
       │       • npx eslint --quiet (必過)│
       │       └─────────────────────────┘
       │
       └── PostToolUse: Bash
               │
               ▼
           ③ Cmd Logger ─────────────────┐
               • 記錄 git/npm/wrangler   │
                 等有意義指令             │ → cmd_count++
               • 更新打卡鐘 live JSON    │
               └─────────────────────────┘
                              │
                              ▼
              ┌─────────────────────────┐
              │ TRACKER UI 「打卡鐘」 │
              │ index.html#punchclock  │ ← 即時看見今日所有
              │                         │   AI session 的活動
              │ • 工作時長              │
              │ • 編輯次數              │
              │ • 指令次數              │
              │ • recent_edits 清單     │
              └─────────────────────────┘
```

### 2.4 資料模型

集中狀態目錄：`~/.claude/state/rsun/`

```
next-action.json              ← 共享：今日交辦（user/AI/hook 都可寫）
onboarded-files-default.json  ← 配置：高風險檔案白名單
session-<id>.json             ← 每 session：onboarded、edits、cmd_count、scenario
session-log.jsonl             ← append-only：所有編輯與指令的歷史
```

TRACKER 端：`~/Projects/TRACKER/data/session-live.json`（hook 寫，前端讀）

### 2.5 關鍵技術決策

| 決策 | 選擇 | 理由 |
|---|---|---|
| Hook 語言 | Bash + Python（內嵌 heredoc）| 啟動快（< 50ms），無需 npm install，跨機器可移植 |
| Hook payload 來源 | stdin JSON（非 env var） | 符合 Claude Code 2024+ 官方 contract，env var 在 hook context 為空 |
| 受保護檔案 | 警告但不封鎖 | 不擋路 — 留 AI 判斷空間，但留下可審計痕跡 |
| 打卡資料儲存 | 本機 JSON 檔（非 cloud DB）| Phase 1 用最簡架構驗證 → 之後再升級 worker endpoint |
| Scenario 偵測 | 關鍵字 grep（非 LLM 判斷）| 零延遲、零成本、足夠準確（Top-7 Scenario 覆蓋 90% 任務）|

### 2.6 邊界條件

**這套機制不擋的事**（刻意設計）：
- AI 仍可改任何檔案，只是會被記錄
- AI 仍可跳過 Scenario，只是會少一層提示
- Push Gate 只擋 `git push`，本地 commit 不擋

**為什麼不全部 hard block？** 因為過度封鎖會讓 AI 在無法繞過時陷入死循環，產出更差。**留可逃生的閘門 + 完整審計記錄** > **絕對封鎖**。

---

## 3. 後續演進路線

| 階段 | 內容 | 預計時間 |
|---|---|---|
| Phase 1 ✅ | 三層 hook 上線、TRACKER 打卡鐘 UI、本機資料 | **已完成（2026-04-24）** |
| Phase 2 | Cloudflare Worker `/api/session-state` endpoint，跨機器同步 | 2026-Q3 |
| Phase 3 | LLM-based Scenario 偵測（取代關鍵字），更精準路由 | 2026-Q4 |
| Phase 4 | Citation graph 整合 — AI 修檔前自動 query 相關 ADR / decisions | 2027-Q1 |
| Phase 5 | 對外開源「AI-Native Dev Loop」框架，作為容晟科技品牌資產 | 2027-Q2 |

---

## 4. 影響評估（Consequences）

**會變得更容易：**
- 新工程師加入：第一天就能跟 AI 一起按 SOP 工作
- 客戶交付審計：每一行 commit 都能追溯到哪個 Scenario、哪個 sub-agent
- 流程改進：打卡資料 → 看哪些 Scenario 最常用、哪些檔案最常被改 → 反推流程瓶頸

**會變得更難：**
- 流程變更需要同步改 hook（不能只改 markdown）
- 新加入的人員需要學 Claude Code hook 機制（學習曲線約 1 週）

**需要持續觀察：**
- AI 是否會「為了避開 Edit Gate 警告」而改用其他工具繞過 → 待 30 天樣本
- Scenario 偵測準確率 → 每月校準關鍵字表

---

## 5. 相關文件

- `~/Projects/TRACKER/CLAUDE.md` — Phase 0–5 完整 SOP、31 隻 sub-agent 派工速查
- `~/Projects/TRACKER/docs/enforcement-loop.md` — 工程實作細節（hook script 內部）
- `~/.claude/hooks/rsun-{session-start,scenario-detect,edit-gate,cmd-logger}.sh` — 實際 hook 程式
- `~/.claude/state/rsun/next-action.json` — 當前 P0 狀態
- TRACKER UI：[index.html#punchclock](../../index.html) — 即時打卡鐘

---

> **設計哲學**：規範不是用來「期待大家遵守」的，是用來「燒進工具讓大家不得不遵守」的。
> 容晟科技的開發流程，從 2026-04-24 起，是一個**可執行的系統**，不只是文件。