Aiderをチームで使う前に：repo-map・architect mode・lint/testを分ける基準

3行まとめ

Repo-map

大規模repoの索引として使う。

Modes

ask、code、architectを分ける。

Git

auto-commitをreview単位で見る。

Tests

lint/testで修正ループを止める。

Aiderはterminalで直接diffを作るため、Git運用が品質の土台になります。

• AiderはterminalでGit repoを直接編集するAI pair programmerです。repo-map、chat mode、Git auto-commit、lint/testの運用を決めると、AI差分をreviewしやすくなります。
• 最初から大きなrefactorを任せるのではなく、ask modeで調査、code modeで小修正、architect modeで設計が重いtaskを扱うように分けます。
• auto-commitやauto-testは便利ですが、reviewできるcommit粒度と安定したtest commandが前提です。最初は小さく始めます。

本文の事実確認には、Aider公式docs、Aider GitHub repository、repo-map、chat modes、lint/test docsを使っています。Xで見かけるAider、repo-map、architect mode、terminal AI pair programmingへの投稿は需要シグナルとして扱い、本文の根拠にはしていません。

この記事でわかること

Scope

編集fileとread-only fileを分ける。

Mode

質問、実装、設計を分ける。

Check

lint/test commandを決める。

Model

cloud/local modelを分ける。

Aiderは速いぶん、どこまで任せるかを先に決めます。

• Aiderをチームで使う時に最初に分ける運用境界
• repo-mapを大規模repoの入口として使う考え方
• ask、code、architect modeの使い分け
• Git auto-commitをreviewしやすい粒度にする方法
• lint/testをAI修正ループの歯止めにする方法
• cloud modelとlocal modelをどう分けるか

Aiderは、IDE中心のagentとは少し違います。terminalで動き、Git repoの中でfileを編集し、必要に応じてcommitします。Vim、tmux、SSH、remote shellのような開発環境にも入れやすい一方で、Git運用がそのまま品質管理になります。

この記事では、Aiderをチーム導入する前に、repo理解、chat mode、Git commit、lint/test、model選択を分けて整理します。

前提知識

項目	内容	見方
Terminal		Git repoでpair programming。
Repo-map		codebase全体のmapを使う。
Chat modes		ask、code、architect、help。
Lint/Test		編集後の自動確認。

AiderはIDE機能より、terminalとGitの流れで理解します。

Aider公式docsでは、Aiderをterminalで動くAI pair programming toolとして説明しています。既存のGit repoでcodeを編集でき、GitHub repositoryのREADMEでも、Aiderがcodebaseのmapを作り、Gitと統合し、自動commitできることが説明されています。

Chat modes docsでは、code、ask、architect、help のmodeが説明されています。Linting and testing docsでは、Aiderが編集後にlintやtestを実行し、失敗を修正しようとする流れが説明されています。

この記事の扱う範囲

項目	役割
repo-map	codebase全体のsymbol mapをcompactに渡す
ask mode	fileを変更せず、質問や調査を行う
code mode	Aiderが直接fileを編集する
architect mode	設計modelと編集modelを分けて変更する
Git auto-commit	Aiderの変更をcommitとして残す
lint/test	編集後の検証と修正ループ

2026年5月31日時点で公開されているAider公式docsとGitHub repositoryを確認しています。導入時には、Aider version、model provider、repoのGit運用、test command、secret管理を確認してください。

注意点

この記事は、Aiderに大規模変更を無条件に任せるための記事ではありません。まず小さなGit diffを作り、reviewできるcommitとtest commandを整える前提です。

まず5つの運用境界に分ける

項目	内容	見方
Context		repo-mapと追加file。
Mode		ask、code、architect。
Diff		編集対象fileとcommit。
Check		lint、test、build。
Model		providerとlocal model。

境界を分けると、Aiderが作ったdiffをreviewしやすくなります。

Aiderの導入では、最初に5つの境界を分けます。

境界	確認すること
Context	repo-map、追加file、read-only file
Mode	ask、code、architectをどう使うか
Diff	Aiderが編集してよいfileとcommit粒度
Check	lint、test、build command
Model	cloud model、local model、architect/editor model

この5つを分けないと、「Aiderに任せた」としか説明できません。実務では、どのfileを読ませ、どのmodeで作業し、どんなcommitを作り、何で検証したかを残します。

terminal-firstの利点

Aiderはterminalで使いやすく、既存のshell workflowへ入りやすいです。Git diffやtest commandをすぐ見られるため、AI差分を手元の運用へ寄せられます。

terminal-firstの注意点

terminalで動くということは、shell command、env、secret、Git stateに近いということでもあります。Aiderに渡すfile、実行するtest command、model providerへ送る内容を意識します。

repo-mapは大規模repoの入口にする

Symbols

classes、functions、signaturesを拾う。

Context

未追加fileの関係を推測。

Tokens

compactにrepoを伝える。

Request

必要fileを追加する判断に使う。

repo-mapは全fileを読む代わりではなく、次に読むfileを選ぶ地図です。

AiderのGitHub READMEでは、Aiderがcodebase全体のmapを作り、大規模projectでもうまく動けるようにすると説明されています。repo-map docsでは、source filesのclasses、functions、methods、signaturesなどを使い、compactなmapを作ると説明されています。

repo-mapは、全fileを丸ごと読む代わりではありません。どのfileが関係しそうかを見つけ、必要なfileを追加するための地図です。

repo-mapで見るもの

観点	内容
symbols	class、function、method、signature
relation	関連しそうなfileやmodule
tokens	contextに入るcompactな情報
next file	追加で読むべきfile候補

repo-mapを過信しない

repo-mapは便利ですが、implementation detailsや最新の意図をすべて理解するわけではありません。大きな変更では、関係fileを明示的に /add して、Aiderに直接読ませます。

判断基準

「どのfileが関係するか分からない」段階ではrepo-mapを使い、「このfileを編集してよい」と決めた段階ではfileを明示的に追加します。

ask・code・architect modeを使い分ける

項目	内容	見方
ask		質問だけでfile変更しない。
code		直接fileを編集する。
architect		設計modelと編集modelを分ける。
help		Aider自体の使い方。

最初からcode modeにせず、調査と設計を分けると手戻りが減ります。

Aider公式docsでは、chat modesとして code、ask、architect、help が説明されています。ask は質問や説明だけでfileを変更しません。code はfileを変更します。architect は設計modelが提案し、editor modelが具体的な編集に落とします。

modeの使い分け

mode	使う場面	注意点
ask	repo調査、仕様確認、影響範囲確認	fileは変わらない
code	小さな修正、test追加、docs更新	diffをすぐreviewする
architect	cross-file refactor、設計が重い変更	設計と編集の両方をreviewする
help	Aider自体の使い方	project作業とは分ける

最初はaskから入る

初回のrepoでは、いきなりcode modeで変更するより、ask modeで「この機能の入口はどこか」「関連fileはどれか」「testは何を走らせるべきか」を確認します。

architect modeの使いどころ

architect modeは、設計判断が必要なtaskに向きます。複数fileをまたぐrefactor、責務分割、API変更、test strategyの変更などです。ただし、設計提案が正しいかは人間がreviewします。

Git auto-commitはreview単位で見る

項目	内容	見方
Atomic		小さな変更ごとにcommit。
Message		commit messageを確認。
Diff		人間がreviewできる粒度。
Undo		gitで戻せる状態にする。

auto-commitは便利ですが、reviewしやすい粒度が前提です。

AiderのGitHub READMEでは、Aiderが変更を自動commitでき、Git toolsでdiff管理やundoがしやすいと説明されています。これはAiderの大きな強みです。

一方で、auto-commitは万能ではありません。commitが大きすぎるとreviewしづらくなります。commit messageが意図とずれている場合もあります。

auto-commitで見るもの

観点	確認すること
粒度	1commitがreview可能な大きさか
message	変更意図が表現されているか
diff	余計なfileが入っていないか
tests	commit前後で何を確認したか
undo	revertやresetで戻せるか

commitを小さく保つ

Aiderに大きなtaskを1回で渡すより、小さなtaskに分けます。docs修正、test追加、実装修正、refactorを分けると、auto-commitの価値が出ます。

lintとtestは修正ループの歯止めにする

項目	内容	見方
Lint		編集fileの問題を早く拾う。
Test		失敗をAiderへ戻す。
Auto-test		編集後に自動で走らせる。
Build		compileをtest commandで見る。

lint/testは、Aiderに任せた差分を小さく修正するための歯止めです。

AiderのLinting and testing docsでは、編集後にlintを実行し、test commandを実行できると説明されています。--test-cmd と --auto-test を使うと、AI編集後にtestを自動で走らせる運用もできます。

lint/testは、AIに任せた変更を小さく修正するための歯止めです。失敗をAiderへ戻し、再修正させられます。

lint/testの使い分け

検証	使いどころ
lint	編集fileのstyleや静的問題
typecheck	TypeScriptや型付き言語の整合性
unit test	変更箇所のふるまい
build	compileやbundleの確認
e2e	UI flowや統合動作

auto-testは安定してから

test commandが不安定なrepoでauto-testを入れると、Aiderがflakeを直そうとして余計な変更をします。まず手動で /test を使い、commandが安定してからauto-testを検討します。

read-only fileとeditable fileを分ける

Editable

Aiderが変更してよいfile。

Read-only

参照だけさせるfile。

Generated

生成物は必要時だけ追加。

Secrets

秘密情報は読ませない。

Aiderはfileを直接編集するため、追加するfileを意識して選びます。

Aiderでは、fileをchatに追加して編集対象や参照対象にできます。teamで使う時は、read-only fileとeditable fileを分けます。

file scopeの考え方

種類	例
editable	変更してよいsource file、test file
read-only	design doc、API spec、既存実装
generated	lockfile、snapshot、build output
secret	.env、credential、private config

secretを読ませない

terminal-first toolでは、local fileへ近づきやすいです。.env、credential、personal config、production dumpは追加しません。必要な情報はmaskしたexampleやdocsへ分けます。

model選択とlocal modelを分ける

項目	内容	見方
Code		編集精度を重視。
Architect		設計推論を重視。
Local		privacyやofflineを重視。
Cost		tokenとcacheを確認。

modelは速さだけでなく、repo内容を送れるかで選びます。

Aiderは、cloud modelだけでなくlocal modelも扱えます。model選択は、編集精度、設計推論、privacy、cost、latencyで分けます。

model選択の軸

軸	見ること
code edit	diff生成の正確さ
architect	設計推論や長い文脈
local	repo内容を外へ出しにくい
cost	token、cache、長文context
latency	terminalで待てる速度

local modelを過信しない

local modelはprivacy面で魅力がありますが、性能やcontext handlingではcloud modelが必要な場面もあります。また、Aider以外のtoolやweb取得を使えば外部通信は発生します。modelだけでなく、workflow全体を見ます。

最小構成の始め方

項目	内容	見方
Ask first		最初はask modeで調査。
Small edit		1fileの小修正から始める。
Manual test		test commandを手動で確認。
Review commit		auto-commitの粒度を見る。

初回は大きなrefactorではなく、Git diffの流れを確認します。

最初は、ask mode、小さなedit、手動test、commit reviewから始めます。

最初の流れ

1. ask modeで関連fileとtest commandを確認する
2. 編集対象fileを明示的に追加する
3. code modeで小さな変更を依頼する
4. /testで検証する
5. Git diffとcommit messageをreviewする

初回に避けるもの

• 大規模refactor
• 複数packageをまたぐ変更
• unstableなtest commandでauto-test
• secretを含むfileの追加
• production deployに近いcommand

最初は、Aiderがどんなdiffを作るか、どのcommit粒度になるかを観察します。

導入初週の進め方

1. 1日目

   ask modeでrepo-mapを確認。

2. 2日目

   小さなcode editを試す。

3. 3日目

   lint/test commandを設定。

4. 5日目

   architect modeを1taskで試す。

5. 7日目

   auto-commit運用をreview。

初週は大きな変更より、reviewできるcommitを作ることを優先します。

導入初週は、Aiderで大きな成果を出す週ではありません。Git diffをreviewできる運用を作る週です。

日	やること	完了条件
1日目	ask modeでrepo-mapを確認	関連fileを説明できる
2日目	1fileの小さなcode editを試す	diffとcommitをreviewできる
3日目	lint/test commandを設定する	失敗時の出力がAiderへ返せる
5日目	architect modeを1taskで試す	設計提案と編集diffを分けて見られる
7日目	auto-commit/auto-test運用をreview	開く範囲と戻し方が決まる

拡大する条件

• commitがreviewしやすい粒度になっている
• test commandが安定している
• secret fileを追加しない運用がある
• ask/code/architectの使い分けが説明できる
• local/cloud modelの使い分けが決まっている

この条件を満たしてから、taskを大きくします。

FAQ

Ask or code?

変更不要ならaskにする。

Architect?

設計が重いtaskで使う。

Auto-test?

commandが安定してから開く。

Local model?

privacyと精度で選ぶ。

迷ったら、Aiderが作るcommitをreviewできるかを見ます。

AiderはIDE agentと何が違いますか

terminalとGit repoを中心に動く点が違います。Aiderはcommit、diff、test commandと相性がよく、Vim/tmux/SSHのような環境でも使いやすいです。

repo-mapだけで十分ですか

十分ではありません。repo-mapは関連fileを探す地図です。編集するfileや細かく確認したいfileは明示的に追加します。

architect modeはいつ使いますか

cross-file refactorや設計判断が必要なtaskで使います。小さなdocs修正やtest追加ならcode modeで十分です。

auto-testは最初から有効にすべきですか

まず手動で /test を使います。test commandが安定し、失敗時の出力が有用であることを確認してからauto-testを検討します。

AiderとOpenHandsはどう使い分けますか

Aiderはterminal pair programmingとGit commit運用に向きます。OpenHandsはruntime/sandboxを含むself-hosted agent運用として見ます。OpenHands側はOpenHandsを自前運用する前にで整理しています。

参照した主な情報源

• Aider Documentation

https://aider.chat/docs/

• Aider GitHub repository

https://github.com/aider-ai/aider

• Aider Docs: Chat modes

https://aider.chat/docs/usage/modes.html

• Aider Docs: Linting and testing

https://aider.chat/docs/usage/lint-test.html

• Aider Docs: Repo map

https://aider.chat/docs/repomap.html

次に読むなら

更新履歴

1. 2026年5月31日

   Aider公式docsのrepo-map、chat modes、lint/test、GitHub READMEを確認して初版を作成しました。

導入時には公式docsと利用中のAider versionを確認してください。

• 2026年5月31日: Aider公式docsのrepo-map、chat modes、lint/test、GitHub READMEを確認し、初版を作成しました。