AI Development Control Log

我不一定看得懂 AI 寫的每一行 code。
但我一定要看得懂，它什麼時候偷偷替我做主。

简体中文 | English

這份東西是什麼？

這是一份給非工程背景創業者、產品負責人、獨立開發者用的 AI 開發控制日誌。

它不是教你寫程式。
它是教你怎麼管理一個很會寫程式、但偶爾會自作主張的 AI 助理。

AI coding agents 很厲害。Claude Code、Cursor、Codex、OpenCode 這類工具，已經可以把一個產品從 0 慢慢堆起來。

但真正嚇人的地方不是 AI 寫錯。
寫錯還能修。

真正嚇人的是：它沒問你，就替你做了產品決策。

你只是叫它改一個小功能，它順手改了核心計算邏輯。
你只是叫它調整畫面，它順手重構一整個模組。
你只是叫它補一個欄位，它順手改了資料庫 schema。
它可能不是故意的。它甚至覺得自己在幫你。

問題是，它沒有告訴你。

這份 repo 要解決的就是這件事。

一句話

Karpathy guidelines 管 AI 怎麼寫 code。
AI Development Control Log 管 AI 有沒有越權。

你不需要看懂 code

你需要看懂這些：

AI 做了什麼？
哪些是你明確要求的？
哪些是 AI 自己決定的？
哪些地方偏離原本規格？
有沒有碰到資料、金流、production、權限、核心計算？
驗證了什麼？沒驗證什麼？
出事怎麼退？

這些是人話。不是 code。

只要 AI 老實寫出來，非工程背景的人也能管理它。

這份規範怎麼來的？

它結合了兩件事。

第一個是 Karpathy-style coding guidelines：

Think before coding：不要亂猜，先講假設
Simplicity first：不要過度設計
Surgical changes：只改該改的，不要順手亂改
Goal-driven execution：要有驗證標準，不要只說「完成」

第二個是 Control Log：

把 AI 的假設寫出來
把 AI 自己做的決定寫出來
把偏離規格的地方寫出來
把取捨寫出來
把不可逆操作擋下來
把驗證和回滾寫清楚

Karpathy 讓 AI 少寫爛 code。
Control Log 讓 AI 不要偷偷當老闆。

什麼時候一定要用？

只要做錯會痛，就用。

特別是：

金流、付款、訂閱、佣金
使用者資料、CRM、隱私資料
資料庫 schema、migration、批次更新
production deploy、cutover、webhook、gateway
權限、登入、auth、secret
核心計算邏輯
多 agent 協作
任何你看不懂，但出事很麻煩的任務

小 typo、單行文案、沒有副作用的小修改，可以不用。

最重要的規則

1. 每個改動都要能追溯到需求

Every changed line should trace directly to the user's request.

如果你叫 AI 改按鈕文案，它卻動到付款邏輯，這不是「順手優化」。
這是越權。

2. AI 自己決定的事情要分開列

AI 可以建議。
AI 可以提出更好的做法。
但它不能默默替你決定。

3. 不可逆操作必須停下問

碰到這些事，AI 必須停：

刪資料
改資料庫結構
推上 production
改金流、付款、訂閱
改權限、auth、secret
改核心計算邏輯
大規模重構

不是寫在最後報告。
是做之前就停下來問。

4. 「已完成」不是證據

AI 說完成，不代表完成。
AI 說測過，不代表真的測過。

它要寫清楚：

跑了哪些測試
哪些通過
哪些沒跑
哪些只是推測
如果出事怎麼回滾

每份回報也應該先標可信度：

✅ 已真實驗證：有工具輸出、測試、live smoke 或 production check 可支撐
⚠️ 部分驗證：只驗證其中一部分，或缺少 live / production 證據
❌ 未驗證：只是推論、閱讀文件、或尚未執行真實檢查

測試類型也要分清楚，不要把 mock test 說成真實可用：

mock：只代表模擬通過
unit：單元測試通過
integration：整合測試通過
live smoke：真實 CLI / API / 服務最小可用檢查通過
production verified：production 環境已確認

5. v0.2 Evidence Layer — 從「AI 自報」升級成「可交叉驗證」

v0.1 把「驗過 / 部分驗過 / 沒驗過」和測試類型標籤分開，已經是一步。
但寫 Log 的人和被記錄的還是同一個 AI —— 這就是楊士弘說的
「被監督者也是報告者」問題。

v0.2 把每個宣稱都綁到一個 客觀、可被重新執行 的證據上，
不再只是 AI 自己說：

子區塊	綁定的客觀物件
9.5.1 改動檔案	`git diff --name-status <BASE>...HEAD`
9.5.2 Diff 摘要（逐檔）	`git diff` + 人工白話
9.5.3 測試結果	原始 pytest / vitest / go test 輸出，不是「通過」兩個字
9.5.4 驗證類型	mock / unit / integration / live smoke / production — 強制標出
9.5.5 Commit Hash / PR 連結	`git rev-parse HEAD` + PR URL
9.5.6 高風險接觸點	DB / 金流 / 權限 / secret / production / 核心計算 / 外部副作用
9.5.7 回滾證據	「可回滾」不算 —— 要真的把 revert / 還原 / 重新部署跑過一次

實作工具：

python scripts/collect_evidence.py --base main
# or
bash scripts/collect_evidence.sh main

會直接吐出 9.5.1 改動檔案與 9.5.3 測試結果，AI 只要貼進去就好，
不用手打。

詳細設計：見 docs/automation/evidence-layer-v0.2.md。
v0.2 模板：

templates/implementation-control-log.v0.2.md
templates/implementation-control-log.zh-TW.v0.2.md
examples/billing-change-control-log.v0.2.md（金流範例，附 v0.2 證據）

會每天記、每天寄嗎？

先講清楚，避免誤會：

預設不會每天自動記。
預設不會每天自動寄。

這個 repo 目前提供的是 任務級 control log 規範與模板。也就是：當你交給 AI 一個非小任務時，AI 應該邊做邊更新 implementation-control-log.md。

如果是長任務、多 agent 任務、或一天內 AI 做了多個自主判斷，建議額外產出：

Daily AI Decision Digest

Daily Digest 的重點不是報工，而是讓使用者知道：

AI 今天自己做了哪些決定？
哪些地方本來應該問使用者？
哪些是真的驗證過？
哪些只是部分驗證或未驗證？
有沒有碰到高風險 gate？
明天使用者需要看哪幾件事？

要每天自動寄送，還需要另外接 automation，例如 GitHub Actions schedule、cron、Hermes、Feishu / Lark bot、Telegram 或 email。這個 repo 會提供模板與範例，但不會憑空替你寄信。

如果要啟用，請先看：docs/automation/optional-delivery-automation.md。

核心原則：

自動寄送是選配，不是預設。
先 local-only，再 draft-first，最後才 send。

語言選擇

Control Log 與 Daily Digest 不能硬寫英文。每份 log 都應該先指定：

輸出語言：zh-TW / zh-CN / en / ja / custom
讀者：Arthur / 創辦人 / 工程師 / 客戶 / 內部團隊
語氣：白話 / 技術 / 高層摘要 / 客戶可讀
技術名詞是否翻成人話：是 / 否

對 Arthur / Nancy 內部使用，預設是：

語言：繁體中文 zh-TW
語氣：白話、CEO 可讀、少技術黑話

公開 repo 可以保留英文文件，但不能只有英文模板。繁中使用者應該能直接看懂 AI 今天做了什麼決定。

快速使用

方法 A：只拿日誌模板

繁中使用者建議直接複製繁中模板：

cp templates/implementation-control-log.zh-TW.md ./implementation-control-log.md

如果你的團隊偏英文，則可使用英文 / 雙語模板：

cp templates/implementation-control-log.md ./implementation-control-log.md

然後要求 AI：

這次任務請邊做邊更新 implementation-control-log.md。不要做完才補。凡是你自行決定、偏離規格、碰到不可逆操作，都要寫進去。

方法 B：Claude Code

把 CLAUDE.md 合併進你的專案 CLAUDE.md。

方法 C：Cursor

把 Cursor rule 複製到你的專案：

mkdir -p .cursor/rules
cp .cursor/rules/ai-development-control-log.mdc your-project/.cursor/rules/

方法 D：Hermes / Agent skill

使用：

skills/ai-development-control-log/SKILL.md

日誌模板

任務級 Control Log 模板：

templates/implementation-control-log.zh-TW.md：繁體中文，給中文使用者直接套用
templates/implementation-control-log.md：英文 / 雙語欄位，適合英文團隊或跨語言團隊
templates/implementation-control-log.zh-TW.v0.2.md：v0.2 證據層，繁中
templates/implementation-control-log.v0.2.md：v0.2 證據層，英文

Daily Decision Digest 模板：

templates/daily-decision-digest.zh-TW.md：繁體中文，每日 AI 決策摘要
templates/daily-decision-digest.en.md：英文，每日 AI 決策摘要

Delivery automation 模板與範例：

docs/automation/optional-delivery-automation.md：選配自動寄送規則
templates/daily-digest-delivery-config.zh-TW.md：繁中寄送設定模板
templates/daily-digest-delivery-config.en.md：英文寄送設定模板

核心欄位：

語言與讀者設定
任務目標
使用者明確要求
待釐清問題 / 假設
AI 自行決定
偏離規格
Surgical Change 檢查
取捨
高風險 / 不可逆操作
驗證結果
回滾方式

回報時請額外標出：可信度、測試類型，以及能支撐結論的真實工具輸出。

驗證腳本

這個 repo 附了一個輕量驗證腳本：scripts/validate.py。

它不是測你的產品功能，而是檢查 protocol kit / repo 是否仍然完整：

必要文件是否存在且不是空檔
SKILL.md 是否有基本 frontmatter
templates/implementation-control-log.md 與 templates/implementation-control-log.zh-TW.md 是否保留核心 section
Daily Digest / delivery automation 模板是否保留安全 section
範例與文章是否仍在預期路徑

驗證模式

python scripts/validate.py --mode repo
python scripts/validate.py --mode kit
python scripts/validate.py --mode strict

mode	用途	是否要求 `logs/agent-decision-digest.md`
`repo`	維護這個 protocol repo 本身，預設模式	✅ 要
`kit`	給 fork / 使用者套用，不強制保留 Nancy 的 live log	❌ 不強制
`strict`	CI / maintainer 嚴格檢查，目前等同 `repo`	✅ 要

預設執行：

python scripts/validate.py

等同：

python scripts/validate.py --mode repo

成功時輸出：

VALIDATION PASSED (repo mode)

失敗時會列出缺失項，例如：

VALIDATION FAILED (repo mode)
- missing: templates/implementation-control-log.md
- template missing section: Verification Results

GitHub Actions 也會在 push / pull request 時執行 repo mode 驗證與測試。

範例

examples/calc-feature-control-log.md：接近核心計算邏輯的功能
examples/billing-change-control-log.md：金流 / 訂閱變更
examples/billing-change-control-log.v0.2.md：同範例的 v0.2 證據層版本
examples/database-migration-control-log.md：資料庫 migration 與 rollback
examples/multi-round-control-log.md：同一任務多輪更新
examples/daily-decision-digest.zh-TW.md：繁中每日 AI 決策摘要範例
examples/daily-decision-digest.en.md：英文每日 AI 決策摘要範例
examples/language-selection-control-log.zh-TW.md：繁中語言選擇 control log 範例
examples/github-actions-daily-digest.yml：GitHub Actions local-only digest artifact 範例
examples/hermes-cron-daily-digest.zh-TW.md：Hermes cron 每日摘要範例

可以分享的文章

如果你想把這套觀念分享給其他人，可以從這篇開始改：

articles/manage-ai-engineer-with-control-log.md

Repo 結構

.
├── README.md
├── README.zh-CN.md
├── README.en.md
├── CLAUDE.md
├── .cursor/rules/ai-development-control-log.mdc
├── skills/ai-development-control-log/SKILL.md
├── templates/
│   ├── implementation-control-log.zh-TW.md
│   ├── implementation-control-log.md
│   ├── implementation-control-log.zh-TW.v0.2.md
│   ├── implementation-control-log.v0.2.md
│   ├── daily-decision-digest.zh-TW.md
│   ├── daily-decision-digest.en.md
│   └── irreversible-operations-checklist.md
├── docs/
│   ├── automation/
│   │   ├── optional-delivery-automation.md
│   │   └── evidence-layer-v0.2.md
│   └── plans/
├── examples/
├── logs/
├── articles/
├── scripts/
│   ├── validate.py
│   ├── collect_evidence.py
│   └── collect_evidence.sh
└── tests/

License

MIT