inSmartBank

AI家計簿アプリ「ワンバンク」を開発・運営する株式会社スマートバンクの Tech Blog です。より幅広いテーマはnoteで発信中です https://note.com/smartbankinc

続・AIのためのオンボーディングドキュメントを整備する (2026年1月版)

Engineering

スマートバンク新春エンジニア駅伝2026も第五区に差し掛かりました*1。 昨日の id:minisera によるクレジットカード番号の混入を防ぐ技術 - inSmartBank はまさにカード決済に携われるエンジニアリングならではの記事でした。打って変わって本記事はSoftware Engineer / Engineering Managerの id:ohbarye が旬と思しきAIトピックをお届けします。

去る2025年3月、弊社が公開した『AIのためのオンボーディングドキュメントを整備する』ではAIコーディングツール活用時に期待した通りの成果物にならないという課題と、その解決策としての「AIのためのオンボーディング整備」について紹介しました。

あれから約10ヶ月が経過する中で起きたツールや周辺状況の変化に合わせ、以前の記事で紹介したAI向けオンボーディングドキュメントを再整理しました。本記事では2026年1月時点でどのように考え、どのような構成でAIのためのオンボーディングドキュメント整備をしたのかをご紹介します。

なお、本記事では「AIのためのオンボーディングドキュメント」はAGENTS.mdにならって”README for agents”と同義といたします。

前提

前記事のおさらい - もともとどんな構成だったか

まず、2025年3月の『AIのためのオンボーディングドキュメントを整備する』（以下、前記事と呼びます）の内容を軽く振り返ってみます。

前記事ではAIが効率よく参照できるようなコーディングガイドラインを次のような構成でプロジェクト内に配置したとご紹介しました。*2

├── .cursorrules.example                     # Cursor専用
└── .ai_guideline/                           # 共通化を目指したディレクトリ
    ├── coding_guide.md                      # 全体的な概要と基本方針
    ├── coding_guide_maintenance_step.md     # ドキュメント自身のメンテナンス方法
    └── docs/
        ├── controllers/                     # コントローラー層の規則
        ├── models/                          # モデル層に関する規則
        ├── security/                        # セキュリティ上の要求事項
        └── testing/                         # テストの書き方

この時点ではスマートバンクでのAIコーディングエージェントのメインストリームはCursorでした。2025年2月にリサーチプレビュー版が出たClaude Codeを使っていた人が数名おり、加えてDevinの利用開始時期でもありました。

ツール利用状況の変遷

一方、10ヶ月経過して社内で利用されるツールにも変化が生じました。2025年12月に社内で実施したアンケートによると開発で利用されているAIコーディングツールは以下の通りです。（24名回答、複数回答可）

ツール名 利用率 利用人数
Devin 87.5% 21名
Claude Code 83.3% 20名
Cursor 33.3% 8名
Codex CLI 33.3% 8名
GitHub Copilot 20.8% 5名
Gemini CLI 4.2% 1名

前回の記事では組織全体でも高々2〜3ツール、かつ複数ツール併用者も大多数ではありませんでした。現在ではほぼすべてのエンジニアが複数のAIエージェントツールを併用する状況です。*3

この変遷の過程でClaude CodeやGitHub Copilotの個別ドキュメントが追加され、今回の整理前は以下のようになっておりました。

.
├── CLAUDE.md                              # Claude専用
├── .cursorrules.example
├── .github/copilot-instructions.md        # Copilot専用
└── ai_guidelines/
    ├── coding_guide.md
    └── docs/
        ├── controllers/api_basic.md
        ├── models/basic.md
        ├── security/auth_modules.md
        └── testing/rspec.md

意外なことに、AGENTS.mdはこのプロジェクトでは未採用でした。

ドキュメントを再整理すべきと思い至った理由

利用ツールの増加に伴いドキュメントの差分が目立つようになった

前項で述べた通り採用されるツールが増えていくと同時に各々のツール固有ファイルが増えていきました。

  • CLAUDE.md (Claude Code専用)
  • .github/copilot-instructions.md (GitHub Copilot専用)
  • .cursorrules.example (Cursor専用)
  • ai_guidelines/ (全ツール共通のドキュメント…のはず)

個別のファイルが増えつつもメンテナンスのされ方がまちまちであったり、コーディングエージェントツールによってオンボーディングの手厚さが異なる状況となっていました。Claude Codeのセッションでメモリー編集を行うとCLAUDE.md は更新されるがその他は更新されない…といった具合で徐々に差分が生まれていったものと思われます。

このような記述差異があることは少なからずツールの成果物・品質・精度に影響を与えていたはずです。弊社は複数のツールを比較・評価することを推奨していますが、このようなドキュメント差分のせいで「ツールAは期待通り動くけどツールBは使えない」のような評価を与えてしまうのは望ましくありません。

ただでさえ実務におけるツールの性能評価は難しい...

ツールや取り巻く状況が変化した

AIコーディングエージェントツール自体や周辺の変化も起きました。特に今回の再整理に関わるものは以下です。

  • 2025年8月にAGENTS.mdが登場
    • Claude Codeを除く各種ツールが対応
    • サブディレクトリに分割することで遅延して読み込む方式でコンテキストを節約可能
  • Cursor Rulesに続いてClaude CodeもRulesに対応
    • サブディレクトリに分割するよりも細かいModuler rulesを設定可能

これらの変化に追従し、より良いドキュメントの整理方法を編み出せるのではと考えました。

再編成の方針：AGENTS.mdへの移行とModular Rules活用

上述のような背景や変化を受けて2026年1月、AGENTS.md とModular Rulesを活用する方針でアプローチでドキュメントを再編成しました。

設計方針

1. AGENTS.mdをハブとした統一

ほぼ全てのツールがAGENTS.mdを読み込むため、ルートディレクトリのAGENTS.mdを共通のハブドキュメントとして配置しました。

# AGENTS.md

プリペイドカードサービスのバックエンドAPI。Ruby on Rails 8.1 (API Only)で構築。

## プロジェクト構成

- `app/`: Rails APIコード（controllers, models, jobs, serializers, policies）
- `spec/`: RSpecテスト、factories、request specs
- `db/`: Ridgepoleスキーマ（`Schemafile`, `schemata/`）、SQLビュー（`db/views/`）
- `config/`: アプリケーション設定、`database.yml`は`DB_*`環境変数を読み込み
(略)

## 技術スタック

(略)

## ビルド・テスト・開発コマンド

(略)

AGENTS.mdに対応していないClaude Code向けにはCLAUDE.mdをシンボリックリンクとして提供します。

2. 層別AGENTS.mdを配置して遅延読み込み

前回の記事で紹介した階層化アプローチがAGENTS.mdでも用いられているため、各層にAGENTS.mdを配置することにしました。

app/
├── controllers/AGENTS.md  # Controller層特化ドキュメント
├── models/AGENTS.md       # Model層特化ドキュメント
├── views/AGENTS.md        # View層特化ドキュメント
db/AGENTS.md               # Database層特化ドキュメント

...

これにより各ツールは個別のディレクトリ内のファイルを参照する際に、その層に特化したドキュメントを遅延して参照できます。

このアプローチはDynamic context discovery*4と呼ばれ、2026-01-06の Dynamic context discovery · Cursorにも詳しく書かれています。

3. Modular Rulesによるコンテキスト最適化

層別ドキュメント遅延読み込みよりもさらに便利なのが、CursorとClaude Codeが対応しているModular Rulesです。ファイルパターンに応じた動的なルール適用を実現できるため、ディレクトリをまたいで参照させたいドキュメントを定義できます。

たとえばcontroller層に関するドキュメントは、shipされる実装 (production code) を編集する場合だけでなくテストファイルを編集する場合にも参照させたいことがあります。そのようなシーンではglobを用いて複数のパス指定をすることで実現できます。

---
(注釈) YAMLフロントマターでglobパターンを指定
      Cursorは `globs` , Claude Codeは `paths` である点に注意
globs:
  - "app/controllers/**/*.rb"
  - "spec/requests/**/*_spec.rb"
---

(注釈) 各ruleファイルからは各ディレクトリに配置したAGENTS.mdを参照させるのみとしています。

@app/controllers/AGENTS.md を参照してください。

これらをCursor, Claude Code向けに用意することにしました。

Cursor向け (.cursor/rules/controllers/RULE.md):

---
globs:
  - "app/controllers/**/*.rb"
  - "spec/requests/**/*_spec.rb"
---

@app/controllers/AGENTS.md を参照してください。

Claude Code向け (.claude/rules/controllers.md):

---
paths:
  - "app/controllers/**/*.rb"
  - "spec/requests/**/*_spec.rb"
---

@app/controllers/AGENTS.md を参照してください。

また、カード決済に絡むコードが Card namespaceにあるとき、Railsではディレクトリ名とnamespaceが一致するように規約が定められているため、globsに "**/card/**/*.rb" を指定すると「カード決済に関連するファイル」を扱うときのみ特定のドキュメントを読ませることができます。

その他にもセキュリティのような横断的な関心事やプロジェクト固有のルールについても、ディレクトリベースではなくglobベースのほうが細かい指定ができて便利です。

なお、このような横断的で特定ディレクトリのAGENTS.md に置きづらいドキュメントは人間にとっても有用な内容である可能性が高いため、トップレベルの docs ディレクトリに配置して共用していくのも良いかと思い始めています。

Before / After の構造比較

ここまで述べたような方針で変更された構成を比べてみます。

Before（2025/03）

.
├── CLAUDE.md                              # Claude専用（独立ファイル）
├── .cursorrules.example                   # Cursor専用
├── .github/copilot-instructions.md        # Copilot専用
└── ai_guidelines/                         # 共通化を目指したディレクトリ
    ├── coding_guide.md                    # メインTOC
    └── docs/
        ├── controllers/api_basic.md
        ├── models/basic.md
        ├── security/auth_modules.md
        └── testing/rspec.md

課題

  • ai_guidelines/への集約が不完全でツール固有ファイルが乱立、記述内容もまちまち
  • AGENTS.md やModular Rulesといった変化への追従がなされていない

After（2026/01）

.
├── AGENTS.md                              # 全ツール共通ハブ
├── CLAUDE.md -> AGENTS.md                 # シンボリックリンク
│
├── .claude/rules/                         # Claude Modular Rules
│   ├── controllers.md                     # YAML frontmatter以外の内容は app/controllers/AGENTS.md を参照させているのみ
│   ├── models.md
│   ├── testing.md
│   └── ...
│
├── .cursor/rules/                         # Cursor Modular Rules
│   ├── controllers/RULE.md                # YAML frontmatter以外の内容は app/controllers/AGENTS.md を参照させているのみ
│   ├── models/RULE.md
│   └── ...
│
├── app/
│   ├── controllers/AGENTS.md              # 層別ドキュメント（遅延読み込み）
│   ├── models/AGENTS.md
│   ├── jobs/AGENTS.md
│   └── ...
│
├── db/AGENTS.md
└── spec/AGENTS.md

改善点された点

  • AGENTS.md標準による統一的なエントリーポイント
  • ツール固有ファイルの削減（Modular Rulesへ集約）
  • 層別配置による遅延読み込みの継承
  • ファイルパターンベースの動的ルール適用

ファイル数は増えていますが、AGENTS.mdをベースとしつつCursor, Claude Code向けにはModular Rulesを活用する形となりました。

（補足）ファイル内容のマージとアップデート

なお、この構成に再整理するにあたり、複数ファイル間の内容の重複・競合・差分を見つけることがありました。 ai_guideline/coding_guide.md にはテストに関して詳細な記述があるが CLAUD.md では数行しかない、といった具合です。

記述をAGENTS.mdに寄せていくにあたり、それぞれのファイルの内容をマージして抜け漏れがないようにする作業もCodex, Opusに依頼しつつ行いました。

今回の再整理でやらなかったこと - モデル・ツールごとの最適化

このたびの変更では特定ツール向けアレンジは極力行わずAGENTS.mdに集約という方針をとりました。Modular Rulesの利用のみツール専用のアプローチですが、ドキュメント本文はAGENTS.md をファイルメンションで参照しているのみです。

個別ツールに関するメンテナンスコスト削減と保守性向上、ツールを切り替えてもドキュメントのベースラインが統一されるといったメリットを取ることを優先したためです。

しかしながら、本来はこの方針がベストではなくモデルやツールごとに異なるプロンプトが最適だと考えています。以下に記すようなモデル特性やツールの実装差異があるためです。*5

1. モデル特性の違い

  • Claude Opus 4.5 Prompting best practices
    • 明確で明示的なプロンプトによく反応する
    • かなり強く従順・高ステアラビリティなので、「どう振る舞ってほしいか」を長めに書く前提
  • GPT-5.2 Prompting guide
    • デフォルトでそこそこバランスのよい挙動をする前提で、「タスク定義・制約・フォーマット」を構造化して書くことが推奨
    • 冗長さやフォーマットは system / top‑level 指示で抑えるくらいで、長いスタイル指示を常に入れる必要はそこまでない

2. ツールの実装差異

  • Claude Code: 対話的コーディング支援、コンテキスト保持能力が高い
  • Devin: タスク実行型エージェント、段階的な計画と実行を重視
  • Cursor: エディタ統合型、リアルタイム補完とコード理解に特化

セッションの都度ファイルを探索する力技で戦うClaude CodeやCodexに大規模コードベースのファイル探索手順を教えるのは効果的かもしれません。一方、内部で独自にインデックスを構築しているDevinやCursorには冗長で余分なコンテキストとなるようにも思います。

これらの理由から、Claude CodeにはCLAUDE.mdとModular Rulesで専用のドキュメントを与える、CodexにはAGENTS.mdにて専用のドキュメントを与える... といった具合でツールやモデルを意識したドキュメント整備が理想ではないかと考えています。

Cursorが公開したDynamic context discovery · Cursorにも以下のように記述されています。*6

Cursor's agent harness, the instructions and tools we provide the model, is optimized individually for every new frontier model we support.

筆者訳: Cursorのエージェントハーネス（モデルに提供する指示とツール）は、サポートするすべてのニューフロンティアモデルごとに個別に最適化されています

AnthropicがAGENTS.mdに迎合しないのもこうした思想のためかと想像していますが、詳しい方がいたらぜひご教示ください。

まとめ

AIコーディングツールが進化・多様化する中、AI向けオンボーディングドキュメントも漸進的な追従が必要です。今回の記事ではAGENTS.mdとModular Rulesの活用により、ツール間の統一性を保ちつつ効率的なコンテキスト管理を行うアプローチを紹介しました。

一方で、「すべてのツールに同じドキュメント」というアプローチへの懐疑についても触れました。本来はモデルごとに最適化されたプロンプトが理想と思いつつも、保守性とのバランスやベースラインを揃えることを重視し、今後の段階的改善に備えています。

AIコーディングツールの進化は速く、「完璧な解」を求めるよりも、今のチームに合った実用的な解を見つけ、走りながら継続的に改善していく姿勢が重要だと考えています。駅伝のように────

というわけでスマートバンク新春エンジニア駅伝2026は続きます。休日を挟んだのち、次回は @rockname による記事をお届けします。

*1:箱根駅伝だと折り返しですね

*2:このプロジェクトは社内で最も大きなコードベースを持つもので、サーバーサイドエンジニアのほぼ全員が開発に関わるものです

*3:特にDevinの使用率が他社と比較して高いのは特徴的です。ref: https://findy-code.io/media/articles/202512_engineer_report

*4:日本語にするなら"動的コンテキスト検出"?

*5:全モデルや全ツールを網羅しているわけではなく一例です

*6:また、ちょうど本記事を書いているときに @hirotea から、「CursorがCodex向けの最適化で悪戦苦闘したことが語られている記事もある」と OpenAI Codex モデル向け Cursor エージェントの改善 · Cursor を教えてもらいました。この場を借りて改めて感謝いたします！

We create the new normal of easy budgeting, easy banking, and easy living.
In this tech blog, engineers and other members will share their insights.