一人如何與 AI agents 共同開發並營運 NT² Vault

NT² Vault 由一人維護並以 AI 協助。Agents 會協助研究想法、把決策變成規格、撰寫 code 與 tests、review 變更、準備翻譯，以及調查營運 signals。

這不代表 agent 可以獨立發佈產品。

真正的槓桿來自把良好的工程習慣，轉成一套人類與 agents 都能遵守的系統：

• 使用 durable context，而非依賴 chat memory；
• 一次處理一個有邊界的 work package，而非模糊 feature request；
• 使用可觀察的驗收條件，而非形容詞；
• 明確核准，而非推測 consent；
• 以 tests 與 review evidence 取代 agent confidence；
• 由 read-only reviewer 把關，而非 self-approval；
• 提供受限的 operations capabilities，而非不受限制的 production access。

本文會把這套系統整理成可移植的 playbook。您不需要知道 NT² 的 repository layout、cloud provider、framework、package manager 或專用 command，就能將它套用到其他專案。

先定義 authority model

選工具之前，先決定誰可以做決策、誰可以執行動作。

我們採用以下模型：

規則很簡單：

Agents 可以產出供 review 的決策草案，但不能默默把 recommendation 變成 authority。

這項分工必須寫進 workflow，而不是留在某個人的腦中。

1. 建立四層 project memory

Agent 表現與 prompt 技巧的關係，往往小於它所取得 project memory 的品質。

一套可移植的做法需要四層。

Layer A — project constitution

這是一份簡短、每個 session 都會載入的文件，包含：

• technology 與 architecture boundaries；
• coding 與 testing rules；
• security invariants；
• 禁止的 shortcuts；
• commit、external write、destructive action 與 deployment 的權限規則。

文件必須短到每個 session 都能完整讀取。詳細說明可以放在其他文件並由此連結。

範例：

## Non-negotiable rules

- UI code 不直接寫入 persistence。
- Secrets 不得出現在 logs、fixtures 或 model prompts。
- 新 dependency 必須說明理由。
- Security-sensitive code 需要獨立 review。
- 沒有明確核准時，不得 commit、deploy 或傳送客戶訊息。

Layer B — current queue

維護一份由人類負責、數量很小的 ready / blocked 清單。

每個項目至少要有：

id: short-stable-id
title: concise outcome
why_now: one sentence
depends_on: []
status: ready

為 active queue 設定上限。對小型團隊來說，十項已經很多。外部 tracker 可以 mirror，但 agent 應該只認一個 canonical source。

Queue 回答的是下一步做什麼；它不能取代回答精確要做什麼的 feature contract。

Layer C — one work package

每個可交付 slice 都建立 versioned work package：

## Goal

要產生什麼 user 或 operational outcome？

## Scope

- 這次會實作什麼
- 這次會變更什麼

## Non-Goals

- 執行期間不得順便加入什麼

## Acceptance Criteria

- [ ] 可觀察的 success behavior
- [ ] 可觀察的 failure behavior
- [ ] Security、privacy、offline 或 performance constraint
- [ ] 必要的 automated 或 manual evidence

這就是 agent 的 execution contract。

Layer D — decision log

記錄應該超越本次 task 的決策：

• 為什麼選擇某種 storage strategy；
• 為什麼刻意不提供某項 capability；
• threat model 發生了什麼改變；
• 哪個 system 擁有某個 contract；
• 何時應重新檢視暫時限制。

Chat 適合用來形成決策，卻不適合保存長期決策。

2. 讓每個 session 都有狹窄的 cold start

新 session 不應從「讀完整個 codebase」開始。

使用以下順序：

1. 讀取 project constitution
2. 讀取 short priority queue
3. 選擇一個 work package
4. 只讀該 package 引用的 architecture 與 source entry points
5. 提案前先整理 assumptions

這能避免三種常見失敗：

1. Context dilution：重要 constraints 淹沒在數千行無關內容中。
2. Roadmap blending：agent 把數個尚未完成的 initiative 混在一起。
3. Stale-memory confidence：把前一次 chat 視為比目前檔案更權威。

每個 work package 只指定一個 implementation owner。平行 agents 可以研究獨立範圍，但不應在同一 working tree 同時編輯同一個 slice。

3. 撰寫足以推翻自信 agent 的驗收條件

Acceptance criterion 必須讓 skeptical reviewer 能判定工作是否完成。

模糊：

- 畫面感覺 polished。
- Sync 很可靠。
- Error handling 很好。

可執行：

- 網路不可用時，save 仍在本機 commit，並顯示明確的 pending-sync state。
- 同一 mutation 收到兩次時，第二次 application 是 no-op。
- Authorization 失敗時，不寫入任何 partial record。
- Logs 包含 operation class 與 result，但不包含 account identifier、
  request body、credential 或 content payload。

Strong criteria 會描述：

• trigger；
• observable result；
• failure result；
• 重要 invariant；
• 所需 evidence。

讓 Non-Goals 具體

「不要 over-engineer」無法被驗證。

應改成：

- 不新增 framework。
- 此 slice 不包含 schema migration。
- 不重新設計相鄰 screens。
- 不建立第二條 persistence path。
- Staging evidence 完成前不 rollout production。

Non-Goals 對 agents 特別有價值，因為它會阻止那些合理、卻未被要求的「改善」。

4. 使用不可跳過的人類 checkpoints

我們的 workflow 有六個有意義的 gates：

Specify -> Plan -> Implement -> Verify -> Review -> Close

Commit 與 release 是 Close 之後另外獲得明確授權的 actions。

Specify 結束時，agent 必須要求人類選擇：

- 核准此 scope
- 修訂
- 視為 disposable prototype

Plan 結束時：

- 核准 implementation
- 重新 plan
- 返回 scope

Close 時：

- 接受 evidence 並關閉
- 重新開啟 implementation
- 暫停且不更改 status

沉默不是核准。先前的「看起來不錯」不代表後續 revision 已獲許可；task 顯示 in progress，也不是跨越下一個 gate 的權限。

Plan 必須包含什麼

有效的 implementation plan 會把每項驗收條件 map 成：

criterion
  -> component 或 boundary
  -> first failing test
  -> minimum implementation
  -> verification evidence
  -> risk 與 rollback consideration

Prompt template：

請規劃這個 work package，但不要修改檔案。

針對每項驗收條件，指出：
- 最小的 code boundary；
- implementation 前應先失敗的 test；
- 判定完成所需的 evidence；
- security、migration、compatibility 與 rollback risks。

遵守所有 Non-Goals。遇到產品決策時請標示，不要自行決定。

5. 一次實作一項 criterion

每項涉及程式的 criterion 都使用 Red → Green → Refactor。

flowchart LR
  AC[一項驗收條件]
  RED[寫 test 並確認 failure]
  GREEN[最小 implementation]
  REFACTOR[保持 green 並改善結構]
  EVIDENCE[記錄 evidence]
  NEXT[下一項 criterion]

  AC --> RED --> GREEN --> REFACTOR --> EVIDENCE --> NEXT

Red

選擇成本最低、但足以證明行為的 test：

執行它，確認 failure 是因為行為尚未存在，而不是 test setup 壞掉。

Green

只實作足以滿足目前 criterion 的內容。重用既有 boundaries，而非建立 parallel architecture。

Refactor

在 test 保持 green 時改善命名與結構。不要把 refactor 當成擴張 Scope 的許可。

Evidence

每項 criterion 都保留：

criterion: offline 時 save 仍留在本機
evidence:
  automated: integration test "transport 中斷時 queues local mutation"
  manual: release candidate 的 offline browser walkthrough
result: pass

Evidence ledger 比「all tests passed」更有價值，因為它保留產品意圖與 verification 之間的連結。

6. 將 implementation 與 review 分離

一個全能 agent 很快，直到它自信地核准自己的錯誤。

分離角色：

Read-only reviewer 很重要。Reviewer 若立即修改自己發現的問題，就可能改變 design，再核准自己改過的版本。

何時 parallelize

適合平行：

• frontend 與 backend impact research；
• threat modeling 與 test design；
• documentation review 與 build verification；
• 在 isolated environments 比較 alternative approaches。

應序列化：

• final scope；
• implementation ownership；
• schema migrations；
• release actions；
• production mutations。

7. 把 security rules 寫成 executable invariants

Security guidance 不該只寫「請小心」。

改寫成 invariants：

- User secrets 絕不離開 trusted client boundary。
- Encryption keys 不可被 export。
- Lock 時清除 sensitive session material。
- 每次 encryption operation 使用 unique nonce。
- Logs 與 operational tools 不暴露 plaintext content。
- Recovery behavior 不建立 server-side password oracle。

接著把每項 invariant map 到：

• code review checks；
• 能自動化時的 static analysis；
• unit 或 integration tests；
• manual security walkthrough；
• 有權阻止 release 的 owner。

定義 AI data planes

不要只說「我們使用 AI」。

逐一記錄：

對 NT² 而言，保管箱明文絕不會送往 AI service。Operations assistance 無法解密內容，customer reply 也必須經人類 review 後才能送出。

8. 讓 CI 以 evidence 為中心，而非一條巨大 command

可移植的 pipeline 可以用 outcomes 表達：

Gate 1: work-package structure 與 status 合法
Gate 2: formatting 與 static analysis 通過
Gate 3: type 與 build contracts 通過
Gate 4: unit tests 與 critical coverage 通過
Gate 5: integration contracts 通過
Gate 6: 受影響的 system tests 通過
Gate 7: dependency 與 security scans 通過
Gate 8: 所需 manual evidence 已附上

每個專案如何 invoke 這些 gates 可以不同；模型本身不變。

執行 affected checks，依風險升級

把變更區域 map 到最小但可信的 gate：

• documentation change → content、references、formatting；
• shared library → library tests 加 affected dependents；
• API contract → integration tests 加 affected clients；
• authentication 或 encryption → full security gate 加 manual walkthrough；
• dependency graph 或 build tooling → full pipeline。

這能維持快速 feedback，又不會教 agents 把 checks 當成 optional。

明確標示 critical coverage

全域 percentage target 經常充滿 noise。直接指定 critical modules——crypto、authorization、parsers、migrations、sync merge logic——並對這些範圍要求較強 coverage。

9. 將 deploy capability 與 deploy authority 分開

Agent 知道如何 deploy，不代表它獲得 deploy 權限。

使用 release state machine：

flowchart LR
  C[Candidate]
  CI[Automated gates]
  S[Staging]
  M[Manual 與 operational checks]
  A[Human approval]
  P[Production]
  O[Post-deploy observation]

  C --> CI --> S --> M --> A --> P --> O
  M -->|fail| C
  O -->|regression| C

每個 transition 都應該有：

• owner；
• required evidence；
• rollback instructions；
• environment isolation；
• audit record。

Release checklist

## Code
- [ ] Approved work packages 已 close
- [ ] Automated gates green
- [ ] 必要 security review 已完成

## Staging
- [ ] 已操作受影響 user journeys
- [ ] Migrations 已套用並驗證
- [ ] Environment 只連到 staging dependencies

## Production
- [ ] Human 已核准 release
- [ ] Rollback path 已準備
- [ ] 已辨識受影響 services
- [ ] Post-deploy checks 已指派

Hotfix 遵循相同原則，只是 scope 更小、timeline 更短：從 production state 開始、做最小修正、驗證受影響 path、release，然後讓 integration branch 與 production state 重新一致。

10. 給 operations agents capabilities，而非 ambient access

Operations agent 不應取得一個已載入所有 credentials 的 shell。

只暴露狹窄 capabilities：

read_health_summary()
read_recent_error_buckets()
read_public_incident_status()
list_open_support_threads()
propose_incident_message()
propose_support_reply()

將 reads 與 mutations 分開：

set_maintenance_mode(value, reason, confirmation)
send_support_reply(thread, approved_body, confirmation)
apply_migration(environment, migration_id, confirmation)

Mutation contract 應要求：

• 明確 environment；
• human confirmation；
• reason；
• 適用時加入 idempotency key；
• authorization check；
• audit event；
• redacted output。

安全 hierarchy 是：

agent tool ⊆ operator interface ⊆ authorized service API

Agent tool 不能建立 normal operator interface 所沒有的 privileged path。

11. 使用會把 evidence 轉成產品工作的 incident loop

Release 後 signal 發生改變時：

1. Detect：找出受影響 outcome，而不只是一行 noisy log。
2. Correlate：比對時間與 releases、configuration changes。
3. Contain：關閉或隔離最小受影響 capability。
4. Reproduce：使用 staging 或安全 fixture，絕不拿 user data 實驗。
5. Fix：建立有邊界的 hotfix package 與 regression test。
6. Verify：確認 user path 與 operational signal 都恢復。
7. Learn：更新 invariant、test、runbook 或 acceptance criterion。

最後一步會讓 AI assistance 產生複利：incident 被轉成 durable context，改善所有未來 sessions。

Human-in-the-loop support

AI 可以：

• 組合 authorized account 與 thread context；
• 尋找相關 public help material；
• 起草 reply；
• 建議 labels 或 routing。

AI 不可以：

• 要求主密碼或還原秘密；
• 檢查私人保管箱內容；
• 默默修改 account state；
• 未經 human review 就送出 reply。

Model 可以減少 context switching，但不能成為最終負責的 operator。

12. 把同一模型套用到 localization 與 content

相同 pattern 也適用於非 code 工作：

canonical source
  -> structural propagation
  -> contextual agent 或 human draft
  -> glossary 與 placeholder validation
  -> human review
  -> publish gate

不要讓 automatic translation service 成為 security 或 product terminology 的未審核寫入路徑。Placeholders、links、code 與 brand terms 應以 deterministic checks 保護。

13. Worked example：新增 inactivity warning

假設另一個產品要在自動 lock 前一分鐘警告使用者。

Work package

## Goal
讓 active user 在現有 idle lock 前選擇保持 session。

## Scope
- 在 T-60 秒顯示 warning。
- 「Continue session」重設既有 idle timer。
- 未操作時，現有 lock path 維持不變。

## Non-Goals
- 不提供 configurable timeout。
- 不延長 cross-device session。
- 不新增 notification service。

## Acceptance Criteria
- [ ] Warning 在 T-60 秒顯示一次。
- [ ] Continue 關閉 warning 並重設 idle tracking。
- [ ] 無操作時執行既有 lock 並清除 sensitive memory。
- [ ] Background-tab behavior 有文件與 test。
- [ ] Log 不包含 secret 或 activity content。

Plan

AC 1 -> timer state -> 使用 fake clock 的 unit test
AC 2 -> 既有 activity reset boundary -> unit + component test
AC 3 -> 既有 lock coordinator -> integration test
AC 4 -> browser visibility behavior -> system test
AC 5 -> logging boundary -> review + log assertion

Human checkpoint

人類必須決定「Continue session」是否需要重新 authentication。這是 product/security choice，不是 agent 可以猜測的 implementation detail。

Implementation

1. 加入 fake-clock test 並確認 RED。
2. 加入最小 warning state。
3. 重用既有 activity reset function。
4. 確認仍由既有 lock function 負責清除 keys。
5. 執行 affected tests。
6. 將 diff 交給 read-only security reviewer。
7. 為每項 acceptance criterion 記錄 evidence。

Release

1. 自動驗證 fake-clock behavior。
2. 在 staging 驗證真實 background-tab behavior。
3. 確認 lock 仍清除 sensitive state。
4. 準備只停用 warning UI、但絕不停用 lock 的 rollback。

這個案例可以使用任何 language 或 framework 實作；可重用的資產是 control structure。

14. 預期會遇到的 failure modes

可移植的結論

AI agents 不會消除工程紀律的必要性，而是會放大包圍它們的系統。

如果系統模糊，它們會更快產生歧義；如果系統具備明確 authority、有邊界的 scope、可測 criteria、獨立 review 與 evidence-backed release gates，它們就能協助一個人負責更廣範圍，而不必假裝自己是一間大公司。

對 NT² 而言，最終 boundary 很直接：

• AI 協助 drafts、implementation、verification 與 investigation。
• 人類負責 product decisions、security acceptance、release 與 customer-visible actions。
• 保管箱明文只留在使用者裝置，不會送往 AI services。

開啟 NT² Vault