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 自己說：

實作工具：

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：英文寄送設定模板

核心欄位：

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

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

驗證腳本

這個 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

預設執行：

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