AI編程協作怎麼避免上下文斷裂？AGENTS.md與Handoff

AI編程協作最常見的失敗，不是模型不會寫語法，而是專案規則沒有被保存成Agent可讀、工程師可審查的Context。需求藏在聊天、架構藏在少數人腦中、Build命令和例外沒有文件時，每次Session都會重新猜測。

可靠做法是把Repository Context拆成穩定層和任務層：穩定層使用AGENTS.md、Repository Instructions、Architecture Decision和Build文件；任務層使用Task Contract、Failing Test、Scope、Checkpoint及Handoff。Agent中斷或換工具後，下一位執行者仍能從Repository恢復狀態。

重點快讀

AGENTS.md可在不同目錄定義Agent規則，通常由最近的檔案影響當前工作。
.github/copilot-instructions.md提供Repository-wide Instructions。
.github/instructions/*.instructions.md可依Path套用特定規則。
部分Coding Agent也會讀取CLAUDE.md或GEMINI.md。
Repo Map只保存影響判斷的架構和依賴，不是自動生成完整檔案列表。
Task Contract定義Goal、Scope、Constraints和Acceptance。
修Bug時先建立Failing Test，再讓Agent修改。
每次Session結束要保存Checkpoint、Pending Work和Known Failure。
Handoff需要讓另一個人或Agent在沒有原Chat的情況下接手。

三層Repository Context

層級	內容	更新頻率
Organization	安全、語言、License和共通工程規則	低
Repository	架構、Build、Test、Code Style和工具	中
Task	Issue、Scope、Acceptance、Checkpoint和Handoff	高

把所有內容塞進單一Instructions檔案會變得重複、衝突和難更新。穩定規則留在Repository，當次任務和狀態留在Task Artifact。

AGENTS.md怎麼用？

AGENTS.md是一種跨Agent的Repository Instructions格式。GitHub Copilot等工具目前支援在Repository內放置一或多個AGENTS.md；Agent工作時，目錄樹中較接近目標檔案的Instructions可覆蓋或補充上層規則。

# AGENTS.md

## Project
Next.js application for internal content workflow.

## Commands
- install: pnpm install
- dev: pnpm dev
- test: pnpm test
- lint: pnpm lint
- build: pnpm build

## Rules
- Use TypeScript strict mode.
- Never edit generated files in src/generated.
- Database migrations require human approval.
- New API routes need auth and rate-limit tests.

## Definition of done
- Tests and lint pass.
- Update docs if behavior changes.
- Summarize risks and unresolved issues.

只寫長期有效規則。
使用可執行命令，不寫模糊要求。
標示不可修改目錄和高風險操作。
提供Definition of Done。
避免和其他Instruction File衝突。

Copilot Repository Instructions

GitHub Copilot支援多種Instructions來源：

檔案	作用
`.github/copilot-instructions.md`	Repository-wide規則
`.github/instructions/*.instructions.md`	依`applyTo`匹配Path
`AGENTS.md`	Agent Instructions和目錄範圍規則
`CLAUDE.md`	部分Agent和Copilot CLI可讀取
`GEMINI.md`	部分Agent和Copilot CLI可讀取

不同Copilot Surface支援的Instructions類型不完全相同。使用前要查看當前Support Matrix，並避免把關鍵安全規則只放在某一個工具專用檔案。

Path-specific Instructions

---
applyTo: "src/api/**/*.ts"
---

- Validate all request inputs.
- Every endpoint requires authentication.
- Do not log access tokens or personal data.
- Add integration tests for permission failures.

Path-specific規則適合Frontend、API、Database Migration、Infrastructure和Test使用不同標準。它降低通用Instructions長度，也讓Agent只在相關檔案工作時載入規則。

Instruction衝突怎麼處理？

同一規則只保留一個Source of Truth。
明確寫出Scope和適用Path。
不要在不同檔案給相反Build命令。
定期執行Instructions Audit。
要求Agent在開始前列出已讀取的Instruction Files。
衝突時停止並要求人類決定。

GitHub Copilot CLI可以顯示已發現的Instruction Files，但一般情況不應假設不同格式存在統一優先級。沒有清楚規則時，最安全的行為是回報衝突。

Repo Map要包含什麼？

repo_map:
  apps/web: customer-facing Next.js app
  apps/admin: internal operations console
  packages/db: schema, migrations, repositories
  packages/auth: identity and authorization
  packages/ui: shared components
  generated/: never edit manually
  deploy/: infrastructure and release scripts

主要Directory和責任。
Domain Boundary。
哪些Package可依賴哪些Package。
Entry Point和Data Flow。
Generated、Vendor和Legacy區域。
Owner和Review Requirement。

Repo Map不是把所有檔名列出來。它應幫助Agent判斷修改位置、依賴方向和不可跨越的架構邊界。

Architecture Decision Record

Architecture Decision Record（ADR）保存「為什麼選擇目前設計」，避免Agent只看到難看的程式就自行重構。

# ADR-014: Keep payment writes synchronous

Status: accepted
Context: webhook retries can create duplicate charges.
Decision: payment creation remains synchronous and idempotent.
Consequences:
- Higher request latency.
- Easier transaction guarantees.
Revisit when: provider supports atomic async idempotency.

ADR讓AI知道某些技術債是有意識取捨。要改變Decision時，先新增或更新ADR，而非只改Code。

Task Contract

task:
  fix password reset token reuse
scope:
  packages/auth and related tests
out_of_scope:
  UI redesign, email template changes
acceptance:
  - old token fails after first successful reset
  - concurrent reset test passes
  - no database schema change
constraints:
  - preserve public API
  - do not log token values

Goal和User Impact。
In Scope與Out of Scope。
相關File和Source。
不可違反Constraint。
Acceptance Tests。
Approval和Rollback。

Failing Test First

重現Bug。
建立或確認Failing Test。
限制修改範圍。
由Agent提出最小修復。
執行相關和完整Test Suite。
Review Diff和安全影響。

先有Failing Test能證明Agent正在修正真正問題，也防止它只改測試或隱藏Error。若無法自動測試，至少建立可重現步驟和Expected Result。

Scope和Diff Budget

任務	建議邊界
Bug Fix	只改相關Module和Tests
Dependency Update	一個Package或相依群組
Refactor	先保持行為，功能變更另開Task
Migration	Schema、Backfill和Rollback分步
Feature	可垂直驗收的小切片

限制修改File數。
限制非必要Formatting。
禁止順手升級無關Dependency。
大型重構拆成多個PR。
超出Scope先停止並回報。

Checkpoint與Resume

checkpoint:
  branch: agent/password-reset-fix
  last_commit: abc123
  completed:
    - reproduced bug
    - added failing concurrency test
  current_state:
    - implementation compiles
    - integration test still fails
  next_steps:
    - inspect transaction isolation
  do_not_repeat:
    - token timestamp approach failed
  risks:
    - possible race in replica reads

Checkpoint不能只寫「進度50%」。它要保存完成、失敗、目前Artifact和下一步，讓下一個Session不必重跑所有探索。

Handoff Artifact

Task和使用者影響。
修改File和原因。
執行過的Command和結果。
Tests、Build和Lint狀態。
未解決問題和Known Risk。
Assumption和Decision。
下一步與Owner。
如何Rollback。

Handoff應存進Repository、Issue或Pull Request，而非只留在Chat。下一個工程師即使沒有原Session，也能判斷是否可以繼續。

Pull Request描述

## Why
Reset tokens could be reused under concurrent requests.

## What changed
- Added atomic consume operation.
- Added concurrency integration test.

## Validation
- pnpm test auth
- pnpm lint
- manual reset flow

## Risks
Database lock contention may increase.

## Rollback
Revert commit and disable concurrent reset endpoint.

PR描述是Agent產出和人類Review之間的正式交接面。它應由實際Diff和Test生成，再由Owner確認。

Generated、Reviewed和Verified

狀態	代表意義
Generated	Agent已產生Code或文件
Reviewed	人類已讀取Diff和設計
Tested	自動或手動Tests已執行
Verified	Acceptance和風險Gate通過
Deployed	已進環境並持續監控

Agent說「完成」通常只代表Generated。正式工作流需要另外記錄Review、Test和Deploy狀態。

跨工具Portability

共通規則優先放AGENTS.md和Repository文件。
工具專用Instructions只放必要差異。
Task和Handoff使用普通Markdown。
Tests和Build Command不依賴Chat產品。
Decision與Source存進Git。
定期用另一Agent讀取專案，測試可接手性。

導入工具前的Publisher、Data Policy和Permission查核可閱讀AI IDE導入前怎麼查？。

最小導入流程

建立Repository-wide Instructions。
補上Build、Test和Architecture文件。
選一個低風險Task。
寫Task Contract和Failing Test。
限制Branch、File和Diff。
Agent執行並保存Checkpoint。
由人Review、Test和Verify。
建立Handoff和PR。
收集失敗，更新Instructions。

常見問題

AGENTS.md可以取代所有專案文件嗎？

不能。它適合摘要Agent需要的長期規則，詳細架構、ADR、API和Runbook仍應分開保存。

要把整個Repository放進Context嗎？

不需要。先提供Repo Map、相關檔案、Instructions和Tests，再依任務動態取得其他內容。

Agent換工具後能繼續嗎？

可以，前提是Task、Decision、Checkpoint、Tests和Handoff保存在Repository，而非只留在原工具Chat。

官方資料

AI編程的可接手性來自Repository，而不是模型記憶。AGENTS.md保存規則，Repo Map保存結構，Task Contract保存目標，Tests保存行為，Checkpoint和Handoff則保存時間。當這些內容都能被下一個人或Agent讀取，上下文才不會隨Session結束一起消失。

AI編程協作怎麼避免上下文斷裂？AGENTS.md、Repo Map、Tests與Handoff