LoginSignup
94
99

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@relu

仕様駆動開発オートエンコーダー コード→AGENTS.md→コード

Last updated at Posted at 2025-09-16

TL;DR
リポジトリの実コードから「仕様（AGENTS.md）」を自動抽出（Encode）し、その仕様から再びコードを生成（Decode）して差分とテストで評価する——この往復（Round-Trip）をCIに組み込むと、仕様と実装のズレを継続的に最小化できます。Spec Kitなどの仕様駆動ツール、Docs-as-Code、OpenAPIコード生成、ADR（MADR）を組み合わせるのが実践的です。 (The GitHub Blog)

なぜ今「コード→AGENTS.md→コード」か

  • 0→1のコードではなく、既存のリポジトリにAIを導入できる。
  • 仕様駆動開発（Spec-Driven Development, SDD）のオープンツールが整ってきた（GitHub Spec Kit など）。コードではなく仕様が主役という前提で、仕様から実働コードを自動生成する流れが現実的になっている。 (The GitHub Blog)
  • AGENTS.md という、エージェント用の統一的な仕様ファイルが台頭。READMEの機械可読版として、セットアップ・コマンド・テスト規約・コーディング規約などを1か所に集約できる。 (Agents)
  • ドキュメントをコードと**同じ運用（Docs-as-Code）**で管理し、CI/CDに組み込むのが定石化。 (Write the Docs)
  • モデル駆動/ラウンドトリップの思想を、LLMとコード生成基盤で実務レベルに落とし込める段階に来た。 (ウィキペディア)

コンセプト：オートエンコーダーとしての開発プロセス

┌─────────────┐     Encode       ┌─────────────┐
│   Codebase   │ ─────────────▶ │  AGENTS.md  │
└─────────────┘                  └─────────────┘
        ▲                              │
        │        Decode                │
        └─────────────◀────────────────┘
               （生成コードをテスト&差分で評価）
  • Encode（逆方向）：既存コード・設定・スクリプト・OpenAPI・テスト・CI定義などからAGENTS.mdを自動生成（抽出/要約/正規化）。
  • Decode（順方向）：AGENTS.md（＋API仕様やADR）を基にエージェント/コード生成器でコード再構成。
  • 損失（Reconstruction Loss）：git diff 行数、Lint/型検査エラー数、ユニット/契約テスト失敗数などの総和を再構成誤差として最小化。
  • この往復自動化は古典的なラウンドトリップエンジニアリングの思想に合致。 (ウィキペディア)

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)

Encode：コード→AGENTS.md（自動抽出パイプライン）

  1. メタ情報の収集
    package.json / pyproject.toml / Makefile / docker-compose.yml / README / CI設定（GitHub Actions 等）を走査し、起動・ビルド・テスト・Lintの手順を抽出。

  2. API境界の取り込み
    OpenAPI/Swaggerの定義があれば、契約としての仕様に取り込む（なければ後述のDecodeで作る）。 (GitHub)

  3. ADRの要約
    MADRフォーマットのADRを見つけて、主要な設計判断（代替案・根拠・結果）をAGENTS.mdに要約リンク。 (Architectural Decision Records)

  4. 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 generated.");

Decode：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からクライアント/サーバーStub/ドキュメントを自動生成でき、契約と実装のドリフトを抑える。 (GitHub)

設計判断の連携（ADR）

  • 設計上の重要な意思決定は MADR テンプレのADRとして残し、AGENTS.mdからリンク。仕様生成/コード生成の根拠追跡が容易になる。 (Architectural Decision Records)

再構成誤差（Reconstruction Loss）の定義と自動評価

CIでEncode→Decodeを回し、以下を集計して「損失」を最小化：

  • 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: Encode (code -> AGENTS.md)
        run: node scripts/encode-to-agents.ts

      - name: Decode (AGENTS.md -> code)
        run: |
          uvx --from git+https://github.com/github/spec-kit.git specify check
          # 生成器にAGENTS.mdを食わせて実装更新（詳細はツールに依存）

      - name: Test & Contract Check
        run: |
          pnpm i
          pnpm lint || true
          pnpm typecheck || true
          pnpm test -- --reporter=junit || true
          npx openapi-diff ./openapi.yaml ./generated/openapi.yaml || true

      - name: Compute Reconstruction Loss
        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: Fail if loss too high
        run: test "${{ steps.roundtrip.outputs.LOSS }}" -le 20

導入ステップ（現実解）

  1. OpenAPI を契約の中心に据える（既存サービスはまず逆生成で叩き台を作る）。 (GitHub)
  2. **ADR（MADR）**で重要な意思決定をMarkdown管理。レビューとCIに組み込む。 (Architectural Decision Records)
  3. AGENTS.md を最小でも用意し、エージェントが守るべき運用規約・禁止事項・テスト前提を明文化。 (Agents)
  4. Spec Kitなどの仕様駆動ツールで仕様→計画→実装の型を整える。 (GitHub)
  5. CIでEncode/Decodeの往復と誤差計測を走らせ、PRで差分が少ないほど良い文化を醸成。ラウンドトリップの定石どおり、同期を自動で保つ。 (ウィキペディア)

実務Tips

  • READMEが充実していればAGENTS.mdは薄くてもOK：人間向けは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で意思決定ログを残し、Encode時にリンク再注入。 (Architectural Decision Records)
  • 往復の破綻：ラウンドトリップは道具でなくプロセス。CIで毎回回す。 (ウィキペディア)

付録：ミニマムなリポジトリ構成

.
├─ AGENTS.md
├─ README.md
├─ openapi.yaml
├─ docs/
│  └─ adr/           # MADRテンプレのADR
├─ src/
├─ tests/
├─ scripts/
│  └─ encode-to-agents.ts
└─ .github/workflows/roundtrip.yml

参考リンク

  • GitHub Blog: Spec-Driven Development のオープンツール紹介（2025-09-02） (The GitHub Blog)
  • GitHub Spec Kit（Specify CLI／メソドロジーと手順） (GitHub)
  • AGENTS.md：エージェント向け標準仕様ファイルの解説/事例 (Agents)
  • Docs-as-Code ガイド（Write the Docs） (Write the Docs)
  • Round-Trip Engineering（概念の整理） (ウィキペディア)
  • OpenAPI Generator（契約からのコード生成） (GitHub)
  • MADR（Markdown Architectural Decision Records） (Architectural Decision Records)

この記事が、仕様を中心に据えた“往復可能”な開発プロセスをチームに導入する一助になれば幸いです。

94
99
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
94
99

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?