🎨

Codex CLIなどで設計書ベースでAgenticな実装を支援するAGENTS.mdを作成しました

に公開
LLM
Codex
Agentic Coding
zennfes2025ai
tech

こんにちは、かがわ(@shinpr_p)です。

Codex CLIが盛り上がっていますね。一時期はClaude Codeの一強かのように思われましたが、Codex CLIもものすごい勢いで進化をしています。

注）本記事での“Codex CLI”は、旧Codexモデルとは別の、現在進化中の開発支援CLIを指しています

私は以前、Codex CLIが出た当初に一度試していたのですが、その時はあまり恩恵を感じられませんでした。最近の盛り上がりを受けて改めて試してみましたが、当時と比べてモデルの性能もそうですがCLI自体の改善も加わり、通常開発利用に耐えうるものに進化しているなと感じました。

私は趣味でClaude Code（というよりはサブエージェント）を活用したAgentic Coding環境の構築をしています。
ここまで使い勝手が向上しているのであれば、Codex CLIでも同様の体験ができる仕組みを作るべきなのでは？というモチベーションが生まれたので、過去の資産を活用し、AGENTS.mdに対応しているLLM向けの設計書ベースかつAgentic Codingのガードレールとなれるようなルールと定義ファイル群を作成しました。

https://github.com/shinpr/agentic-code

設計書駆動なAgentic Codingとは？

Agentic Codingは簡単にいうと「AIエージェントが自律的にコーディングタスクを実行する開発手法」です。私は、元の仕組みもですが人間の介入を最小限にしつつも一定水準の品質が保証された開発ができる状態を目指しています。

実装を自律的に行ってもらうには、振る舞いを確認し軌道修正できることが重要です。
正しい振る舞いを明らかにするには、設計書が必要です。

そのため、対話的に設計書を作り、それをもとにタスクの計画やテストが作られれば、自律的な実装が可能になるよね？というのが基本的な考え方になります。

本プロジェクトの特徴

AGENTS.md標準に準拠

このプロジェクトは AGENTS.md に準拠させました。

AGENTS.mdは、OpenAI・Google・Cursorを含む複数関係者やコミュニティで合意形成が進むオープン仕様です。AGENTS.mdに則っておけば、多くのLLMで恩恵を受けられるだろうと踏んでいます。
元のプロジェクトではClaude Codeに特化していたので、サブエージェントという仕組みを使えました。精度に寄与する一方でロックインしていることから、今回のように新しい流れに乗ることが困難になります。特別な仕組みは使えないものの、標準に則ることで素早く新しいものを試すことができることを今回はメリットとして選択しました。

タスク指向アプローチ

コーディングエージェントが担う開発における作業をタスクとして分解し、それぞれのタスクに対する目的や作業手順、完了条件などを定義しています。

AGENTS.mdにはすべてのタスクは task-analysis.md から始まるということを大原則として定めています。この task-analysis.md がユーザーの指示を理解し、どのような種類のタスクなのかを見極め、適用すべきタスク定義を選択するという流れです。

タスクは現状以下の5種類が存在します。小規模タスクの場合は要求に合わせたタスク定義を元に作業をし、中規模以上であればワークフローに沿った作業をレコメンドします。もちろん、個別タスク単位での実行も可能です。

  • implementation
  • prd-creation
  • quality-assurance
  • technical-design
  • work-planning

小規模タスクの場合

  • タスクタイプ例（ユーザーリクエスト）: Slack Botを作りたい
  • 規模: 1-2ファイル
  • パス: 直接実行 → implementation.md

中〜大規模タスクの場合

  • タスクタイプ例（ユーザーリクエスト）: Slack Botを作りたい。Gemini API経由でLLMに接続し、ユーザーへ応答を返す。Slackは独自の文字装飾を用いているのでMarkdownからの変換も必要。
  • 規模: 3ファイル以上
  • パス: ワークフロー（agentic-coding.mdで定義した設計書作成から実装までの一連の流れ）の推奨

プログレッシブルールローディング

私が仕組みを作ると、どうしてもルールや定義が多くなってしまいます。
それらすべてを最初から読み込んでしまうとコンテキスト枯渇につながることと、必要なコンテキストがぼやけてしまうため、タスクに応じたタスク定義、タスクの実行に必要なルールを必要になった時に読み込むようにしています。
設計書駆動なAgentic Codingフルセットのワークフローを完走すると、結局は全てのルールを読み込むことになってしまいますが、LLMの性質として最初と最後のコンテキストが重視される傾向があるため、タスクに必要なルールが必要なタイミングで注入されることの恩恵はあります。
また、単体のタスク実行であれば、不要なルールを読み込まないので、コンテキスト枯渇対策の効果は発揮されます。

これを実現するためには、ルールもタスクも「単一責務」を負うように意識することが重要になります。責務境界が曖昧だと、不要なルールファイルを読み込む必要が生じ、最適化がなされません。

Plan Injection（計画注入）メカニズム

これは、私が誤って古いCodex CLIを使った結果たどり着いた仕組みなのですが、LLMに「ルールファイルを読み込んでください」といっても読んでくれるかどうかは定かではありません（古いCodex CLIでは悉く無視されました、かなしい）。
そのため、「このタスクを実行する際には、BLOCKING READというルールファイルを読むまで実行をブロックするステップを、計画に組み込んでください」とタスク定義の冒頭に記載しています。

LLMは早く実行し結果を出すことを重視する傾向があります。その挙動を制御するために、LLMの実行計画に“ルール読了のブロッキング手順”を含めるよう促しています。そうすることで作業が進行したとしても忘れられることなくルールファイルが読み込まれるようになります。

実際の挙動を紹介（一部抜粋）

タスク分析 -> 設計 -> 計画 -> 実装（実装 -> 品質チェック -> コミット）の一連のワークフローの中から、一部をピックアップして紹介します。

タスク分析のやり取り
▌ slack botを作りたいです。gemini api経由でLLMに接続し、ユーザーへ応答を返す。slackは独自の文字装飾を用いているのでMarkdownからの変換も必要です。レイヤードアーキテクチャで作成したいです

• Ran date
  └ No such file or directory (os error 2)

• Ran date

• Explored
  └ Read metacognition.md
    List ls -la
    Read task-analysis.md, task-rule-matrix.yaml, ai-development-guide.md, rules.md, testing.md, documentation-criteria.md, implementation-approach.md
    List ls
    Read package.json, README.md

• I'm organizing the key steps so far: understanding the request, estimating task scale, and identifying the need to ask the user about following an agentic
  workflow due to medium complexity. I'm preparing to create a task plan that tracks completed rule reads and sets the stage for future steps, ensuring the
  final message includes a recommendation plus user confirmation before proceeding.

• Updated Plan
  └ Documented blocking reads from task-analysis rule selection; all required rules loaded and tracked per plan injection requirement.
    ✔ Load rule .agents/rules/language/rules.md
    ✔ Load rule .agents/rules/language/testing.md
    ✔ Load rule .agents/rules/core/ai-development-guide.md
    ✔ Load rule .agents/rules/core/documentation-criteria.md
    ✔ Load rule .agents/rules/contextual/architecture/implementation-approach.md

• I'm organizing all required steps into a clear final message: verifying rule statuses, summarizing task analysis including success criteria and resources,
  presenting the mandatory Step 4 rule selection block with required and conditional rules, showing plan injection evidence for blocking reads, and finishing
  by prompting the user to approve proceeding with the recommended agentic-coding workflow for this medium-scale implementation.

> Rule Status

  - ✓ .agents/rules/core/metacognition.md — active from session setup
  - ✓ .agents/context-maps/task-rule-matrix.yaml — loaded for rule selection

  Analysis

  - Goal: build a Slack bot that routes user prompts to Gemini via API, converts Markdown to Slack formatting, and responds through Slack in a layered
  architecture.
  - Task type: Implementation (new feature); expected to create infrastructure/adapters, application services, and formatting utilities (≥3 files) ⇒ Medium
  scale.
  - Resources: Slack Bolt/Events API docs, Google Gemini API docs (server-side), Markdown→Slack conversion references (e.g., Block Kit docs), existing project
  conventions.
  - Success criteria: Slack bot responds to messages via Gemini with configurable tokens; Markdown content rendered correctly in Slack formatting; layered
  architecture boundaries enforced; unit tests for formatting/service layers; all required quality commands (tests/build/lint/type-check if present) succeed.
  - Constraints/assumptions: Node.js/TypeScript stack (per repo tooling); Slack permissions/bot tokens available via environment; Gemini API key provided; no
  existing codebase to extend beyond new feature.

  [RULE SELECTION CHECKPOINT]
  Task Type: Implementation
  Task Scale: Medium
  SESSION_BASELINE_DATE: 2025年 9月18日 木曜日 11時28分34秒 JST

  Path Recommendation:
  - Workflow recommended: .agents/workflows/agentic-coding.md (medium-scale feature with new integrations)

  Required Rules [BLOCKING READS - MUST BE LOADED]:
  ✓ .agents/rules/language/rules.md - LOADED - applying coding standards for new feature implementation
  ✓ .agents/rules/language/testing.md - LOADED - enforcing mandatory TDD and quality gates
  ✓ .agents/rules/core/ai-development-guide.md - LOADED - avoiding implementation anti-patterns and ensuring best practices

  Conditional Rules [LOAD IF CONDITION MET]:
  ✓ .agents/rules/core/documentation-criteria.md - LOADED - trigger: medium scale requires design/work-plan guidance
  ✓ .agents/rules/contextual/architecture/implementation-approach.md - LOADED - trigger: medium scale architecture strategy selection

  VERIFICATION: All required rules active in working memory

  [PLAN INJECTION FROM task-analysis - Rule Selection]
  Injected BLOCKING READs from rule selection:
  ✓ .agents/rules/language/rules.md - required rule
  ✓ .agents/rules/language/testing.md - required rule
  ✓ .agents/rules/core/ai-development-guide.md - required rule
  ✓ .agents/rules/core/documentation-criteria.md - medium-scale requirement
  ✓ .agents/rules/contextual/architecture/implementation-approach.md - medium-scale conditional rule

  This medium-scale feature would benefit from the structured agentic-coding.md workflow (design doc + work plan). Do you approve proceeding with that
  workflow?
設計書（ADRとDesign Doc）の生成
• Explored
  └ Read technical-design.md
    List ls
    Search rg --files

• I see the repo is minimal with no docs or code, so I need to capture that in a design doc under a new docs/design folder. I also have to update the plan to
  mark the design step as in progress, mention the technical design reference, and prepare an ADR due to the new external dependencies like Slack and Google
  Gemini. I’m organizing the design around a layered architecture covering interface, application, domain, and infrastructure layers, and I’ll perform a
  metacognition gate before writing anything. Next, I'll craft the design doc and ADR while making sure the plan injection and status updates align with the
  project’s progress.

• Updated Plan
  └ ✔ Phase 1 – Requirements analysis: clarify Slack bot functional/non-functional needs and constraints
    □ [BLOCKING READ] .agents/tasks/technical-design.md then draft design doc for layered Slack-Gemini integration
    □ [BLOCKING READ] .agents/tasks/work-planning.md then create work plan from design
    □ [BLOCKING READ] .agents/tasks/implementation.md then execute implementation tasks per plan
    □ [BLOCKING READ] .agents/tasks/quality-assurance.md then run QA checks and prepare handoff summary

• I'm organizing the plan to produce a design doc and an ADR file, including directory setup and content structure with options and trade-offs for Slack-Gemini
  integration. I'll handle the actual file creation before responding with the summarized compliance and plan injection evidence.

• Ran mkdir -p docs/adr docs/design


• Ran
  └ cat <<'EOF' > docs/adr/ADR-0001-slack-gemini-integration.md
    # ADR-0001 Slack/Gemini 連携方式
    ...
    EOF


• I'm drafting a detailed design doc with sections like architecture overview, components, data flow, and integrations focusing on Slack and Gemini. I’m
  including notes on libraries like @slack/bolt and @google/generative-ai, acceptance criteria, testing strategies, risk assessments, and checklists—also
  clarifying there’s no PRD or existing codebase, and referencing search efforts to confirm that.


• Ran
  └ cat <<'EOF' > docs/design/slack-gemini-bot-design.md
    ...
    EOF


• I'm putting together the final message to the user that confirms plan injection with evidence, rule verification, gating checklist status, references to the
  ADR and design docs with line numbers, and includes a metacognition self-assessment before asking for approval to proceed to the next phase. The message will
  be in Japanese and follow the specified bullet structure carefully.

> [PLAN INJECTION FROM technical-design.md]
  Injected to work plan:
  ✓ BLOCKING READ: .agents/rules/core/documentation-criteria.md – ADR/Design Doc criteria
  ✓ BLOCKING READ: .agents/rules/contextual/architecture/implementation-approach.md – strategy選定
  Status: VERIFIED

  Rule Status Verification
  ✓ .agents/rules/core/metacognition.md
  ✓ .agents/rules/core/documentation-criteria.md
  ✓ .agents/rules/contextual/architecture/implementation-approach.md

  技術調査・ゲート確認

  - 既存 PRD/設計/ADR はなし、コードベースも未実装 (rg --files 調査)。
  - Slack/Gemini 関連の既存実装や類似機能は未確認。
  - プロジェクト構造・セッション日付・計画項目を確認済み。

  成果物

  - ADR: docs/adr/ADR-0001-slack-gemini-integration.md:1
  - 設計書: docs/design/slack-gemini-bot-design.md:1
      - 要件、レイヤード構成、データフロー、テスト戦略、リスク、受け入れ基準を網羅。

  メタ認知（After Completion）

  - 目的に沿った最小の設計か: 3層構造で要件を満たす最小構成と判断。
  - 想定されるリスク: レイテンシと API エラーを重点管理。
  - 次フェーズで必要な情報: 設計書に基づく作業分解と依存関係のみ。

  ご確認いただき、設計内容に問題なければ Phase 3（ワークプラン作成）へ進んでよいかご指示ください。

作業計画書には以下のように1コミットの粒度のタスクが列挙されます。
現状結合・E2Eテストを定義するタスクがないため、単体テストのみが実行されます。

## Task 3: Markdown→Slack フォーマッタの TDD

### Entry Conditions
- [ ] Task 2 完了
- [ ] 変換仕様（太字・段落）が明確
- [ ] TDD 準備

### Scope [Max 2 files or split]
- Files affected: `src/infrastructure/formatters/markdownToSlackFormatter.ts`, `src/infrastructure/formatters/__tests__/markdownToSlackFormatter.test.ts`
- Components: フォーマッタ本体とユニットテスト

### Implementation Steps (TDD + Commit)
1. RED: 変換要件（太字、段落）を網羅するテスト作成
2. GREEN: 実装で全テストを通す
3. REFACTOR: パターン抽出と可読性向上
4. VERIFY: `pnpm test`
5. COMMIT: 1 タスク = 1 コミット

### Exit Conditions
- [ ] 変換テストが成功
- [ ] コード品質が確保（lint, type-check 後に確認予定）
- [ ] 変更をコミット
- [ ] チェックボックス更新

### Dependencies
- Depends on: Task 2
- Blocks: Task 5

実際に触ってみるには？

ここまでの実行ログを見て「試してみたい」と思った方に向けて、最小限のセットアップ手順を用意しました。
とりあえず作ってもらいたいものを言うだけでも要件を解析して動いてくれるのでプロジェクトをセットアップし、LLMと対話してみてください。
プログラミング言語については現状TypeScriptのみ、詳細なルールを定義しています。TSで試す方は--lang=typescriptを指定してください。

# 1. Create project
npx github:shinpr/agentic-code my-project                    # General (works with any language)
npx github:shinpr/agentic-code my-project --lang=typescript  # TypeScript-specific rules

# 2. Enter directory
cd my-project

# 3. Launch your AI coding agent
codex  # OpenAI Codex CLI (recommended)
# Or: cursor, aider, github copilot, etc.

今後の拡張について

現在は、設計書から実装までの流れに必要な最小セットを作成した状態です。
途中でも書きましたが結合・E2EテストをAC(Acceptance Criteria: 受け入れ条件)から生成する仕組みがまだ未整備なので、近々移植してくる予定です。

簡単に移植元でやっていることを書きます。

  • ACを 機能/UX/技術/統合/定量/品質 に分解し、測定可能な検証観点 に変換
  • 統合・E2Eテストのスケルトンファイルを作成
  • 各テストに @category / @dependency / @complexity のメタ情報を付与（後工程で活用）

また、今回言語を選択できるようにしたので、用意しているTypeScript以外の言語のルールも整備していきたいです。ただ、私が今TS以外の開発案件がないため、お手伝いしていただける方がいたら嬉しかったりします。

さいごに

AGENTS.mdとCodex CLIに対応することでモデルの性質の差異にも少し詳しくなれました。
LLM界隈は変化量がバグっているので、今後も手広く手を出していかないとなと改めて感じました。

もしよければみなさんもこのAGENTS.mdとルール・タスク定義集を使ってみてください！

https://github.com/shinpr/agentic-code

Discussion