小編精選 - 技術文章翻譯 · 09月19日

規範驅動開發自動編碼器程式碼 → AGENTS.md → 程式碼

TL;DR
從實際代碼自動提取「規範（AGENTS.md）」（編碼），再從該規範生成代碼（解碼），並通過差異和測試進行評估——將這一往返（Round-Trip）整合進CI中，可以持續最小化需求與實作之間的差距。實務上結合如Spec Kit等的需求驅動工具、Docs-as-Code、OpenAPI代碼生成、ADR（MADR）是可行的。 (The GitHub Blog)

為什麼現在是「代碼→AGENTS.md→代碼」

可以在現有的代碼庫中引入AI，而不是從零到一的代碼。
需求驅動開發（Spec-Driven Development, SDD）已有開源工具逐漸成形（如GitHub Spec Kit）。以規範為主的假設，使得從規範自動生成可運行代碼的流程變得現實可行。 (The GitHub Blog)
出現了作為統一規範文件的AGENTS.md。作為README的機械可讀版本，可以將設置、命令、測試規範、代碼規範等集中到一處。 (Agents)
以Docs-as-Code的方式管理文檔，並將其納入CI/CD已經成為常態。 (Write the Docs)
現在已經來到了能夠將模型驅動/往返的思想落實到LLM和代碼生成基礎的實務層面的階段。 (維基百科)

概念：作為自動編碼器的開發流程

┌─────────────┐     編碼       ┌─────────────┐
│   代碼庫    │ ─────────────▶ │  AGENTS.md  │
└─────────────┘                  └─────────────┘
        ▲                              │
        │        解碼                │
        └─────────────◀────────────────┘
               （通過測試&差異評估生成代碼）

編碼（逆方向）：自現有代碼、設置、腳本、OpenAPI、測試、CI定義等自動生成（提取/總結/標準化）AGENTS.md。
解碼（順方向）：基於AGENTS.md（加上API規範或ADR）的信息，利用代理/代碼生成器進行代碼重構。
損失（重構損失）：以git diff的行數、Linter/類型檢查錯誤數、單元/契約測試失敗數等總和作為重構誤差來最小化。
這一往返自動化契合了古典的往返工程思想。 (維基百科)

AGENTS.md 的最小模板（例）

# AGENTS.md

## 專案概述
- 目的：將圖片在專輯中進行整理的Web應用
- 非功能性：優先考量本地運行，啟動在10秒內，必須有E2E測試

## 設置 & 執行
- 依賴：`pnpm install`
- 開發伺服器：`pnpm dev`
- 正式建置：`pnpm build`
- 測試：`pnpm test`

## 代碼規範
- TypeScript + ESLint + Prettier
- 未使用React的Server Components

## 重要命令
- Lint：`pnpm lint`
- 類型檢查：`pnpm typecheck`

## 生成任務的期待
- 新功能必須首先添加單元測試
- 現有API需遵循OpenAPI架構

規範的重點不在於「面向人類的README」，而是面向代理的步驟與限制。建議將AGENTS.md放在庫的根目錄下。 (Agents)

編碼：代碼→AGENTS.md（自動提取管道）

收集元數據
掃描package.json / pyproject.toml / Makefile / docker-compose.yml / README / CI設置（如GitHub Actions），提取啟動、建置、測試、Lint的步驟。
導入API邊界
如有OpenAPI/Swagger的定義，將其作為契約的規範納入（如沒有，則在後文的解碼中生成）。 (GitHub)
摘要ADR
找到MADR格式的ADR，將主要設計決策（替代方案、依據、結果）摘要並鏈接進AGENTS.md。 (建築決策記錄)
整備Docs-as-Code
將文檔在庫中進行版本控制，並通過PR審查或CI進行檢查。 (Write the Docs)

Node.js 骨架（提取器）

// scripts/encode-to-agents.ts
import fs from "node:fs";
import path from "node:path";

function readIf(p: string) { try { return fs.readFileSync(p, "utf8"); } catch { return ""; } }

const pkg = JSON.parse(readIf("package.json") || "{}");
const scripts = pkg.scripts ?? {};

const template = `# AGENTS.md

## 設置 & 執行
${scripts.install ? `- 依賴：\`${scripts.install}\`` : "- 依賴：`npm ci`"}
${scripts.dev ? `- 開發伺服器：\`${scripts.dev}\`` : ""}
${scripts.build ? `- 正式建置：\`${scripts.build}\`` : ""}
${scripts.test ? `- 測試：\`${scripts.test}\`` : ""}
${scripts.lint ? `- Lint：\`${scripts.lint}\`` : ""}
${scripts.typecheck ? `- 類型檢查：\`${scripts.typecheck}\`` : ""}

## API/契約
- OpenAPI: ${fs.existsSync("openapi.yaml") ? "openapi.yaml" : "未定義（要生成）"}

## ADR
${fs.existsSync("docs/adr") ? "- MADR 存在（docs/adr 下）" : "- ADR 未整備"}

## 代碼規範
- ${fs.existsSync(".eslintrc") ? "ESLint" : "ESLint 未設定"}
- ${fs.existsSync(".prettierrc") ? "Prettier" : "Prettier 未設定"}
`;

fs.writeFileSync("AGENTS.md", template);
console.log("AGENTS.md 已生成。");

解碼：AGENTS.md→代碼（生成＋重構）

選擇Spec Kit（Specify CLI）或喜好的AI編碼代理（Claude Code / Copilot / Gemini / Cursor等），進行從規範到實作的推進。 (GitHub)

例子：利用Spec Kit的初始化及規範化

# 初始化專案（可選擇代理）
uvx --from git+https://github.com/github/spec-kit.git specify init my-app --ai claude

# 撰寫規範（/specify, /plan, /tasks 是代理的擴展命令）
# 在/specify中提出功能需求，/plan中確定技術方針，/tasks中同意實作任務

Spec Kit強調「規範→計畫→任務→實作」的階段性精緻化。 (GitHub)

API代碼生成（OpenAPI）

# 例：利用OpenAPI Generator生成TypeScript客戶端
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml -g typescript-fetch -o ./generated/api-client

可從OpenAPI自動生成客戶端/伺服器存根/文檔，以抑制契約與實作之間的漂移。 (GitHub)

設計決策的關聯（ADR）

重大設計決策需作為MADR模板的ADR保存，並鏈接至AGENTS.md。這樣將便於追蹤規範生成/代碼生成的根據。 (建築決策記錄)

重構誤差（Reconstruction Loss）的定義和自動評估

在CI中執行編碼→解碼，並匯總以下內容以最小化「損失」：

git diff --shortstat 的變更行數（需求與實作之間的差距）
測試失敗數量（單元/整合/契約）
Lint/類型錯誤數量
OpenAPI 架構偏差（API契約違反）

例：GitHub Actions（擬似）

name: roundtrip
on: [push, pull_request]
jobs:
  roundtrip:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: 編碼 (代碼 -> AGENTS.md)
        run: node scripts/encode-to-agents.ts

      - name: 解碼 (AGENTS.md -> 代碼)
        run: |
          uvx --from git+https://github.com/github/spec-kit.git specify check
          # 將AGENTS.md傳遞給生成器以更新實作（具體依賴于工具）

      - name: 測試 & 契約檢查
        run: |
          pnpm i
          pnpm lint || true
          pnpm typecheck || true
          pnpm test -- --reporter=junit || true
          npx openapi-diff ./openapi.yaml ./generated/openapi.yaml || true

      - name: 計算重構損失
        run: |
          CHANGES=$(git diff --shortstat | awk '{print $4}')
          LINT=$(jq '.summary.errorCount' ./eslint-report.json 2>/dev/null || echo 0)
          FAIL=$(grep -c "<failure" junit.xml 2>/dev/null || echo 0)
          LOSS=$(( CHANGES + LINT + FAIL ))
          echo "LOSS=$LOSS" >> $GITHUB_OUTPUT

      - name: 損失過高時失敗
        run: test "${{ steps.roundtrip.outputs.LOSS }}" -le 20

導入步驟（現實解）

將OpenAPI作為契約的核心（對於現有服務，首先通過反向生成製作基礎架構）。 (GitHub)
透過ADR（MADR）對重要的設計決策進行Markdown管理，並將其納入審查及CI中。 (建築決策記錄)
最低限度地準備AGENTS.md，並明確代理需遵守的運作規範、禁止事項、測試前提。 (Agents)
利用Spec Kit等需求驅動工具整合需求→計畫→實作的程序。 (GitHub)
在CI中執行編碼/解碼的往返及誤差計算，培養PR中差異越少越好的文化。依樣畫葫蘆保持同步自動化。 (維基百科)

實務技巧

如果README內容豐富，AGENTS.md可以薄弱：人類使用的README，代理使用的AGENTS.md實現分工。 (Upsun Developer Center)
對於支持不佳的代理，可以從CLAUDE.md等進行 導向至AGENTS.md的重定向以合併。 (Builder.io)
基於Docs-as-Code的前提，對文檔同樣應進行代碼審查和測試（鏈接是否失效、lint、樣本執行）。 (Write the Docs)

易錯點與對策

規範不明確：在AGENTS.md中明確「輸入/輸出/約束/範例」。將OpenAPI作為唯一的真實資料來源。 (GitHub)
生成的波動性：透過階段性提示（/specify→/plan→/tasks）來固定範疇。Spec Kit的做法有效。 (GitHub)
設計的漂移：透過MADR保存決策紀錄，在編碼時重新注入鏈接。 (建築決策記錄)
往返失敗：往返是一個過程而不是工具，要在CI中每次執行。 (維基百科)

附錄：最小化的庫結構

.
├─ AGENTS.md
├─ README.md
├─ openapi.yaml
├─ docs/
│  └─ adr/           # MADR模板的ADR
├─ src/
├─ tests/
├─ scripts/
│  └─ encode-to-agents.ts
└─ .github/workflows/roundtrip.yml