275 Views
March 18, 26
スライド概要
コーディングエージェント入門
■ドローンやロボットを自作することを通じて制御や関連技術の生涯勉強情報を提供■工学博士■防大航空宇宙→筑波大博士■陸自→対戦車誘導弾等の装備品開発→高専教員→大学教員■ロボットランサー優勝→マイクロマウスニューテクノロジー賞受賞■指導者としてつくばチャレンジバンナム賞→飛行ロボコンマルチコプタ部門1位等々■北海道函館出身
コーディングエージェントとは 定義 AI がターミナル(黒い画面のコマンド入力画面)上でコードを読み書 きし、ビルド・テスト・変更履歴の記録まで自律的に実行するツール 動作 範囲 実行 履歴管理 チャット AI コーディングエージェント 対話(コピペが必要) ファイルを直接編集 1 ファイルの断片 プロジェクト全体 ユーザーが手動実行 ビルド・テストも自律実行 関与しない 変更の記録・共有まで なぜターミナルで動くのか: エディタに依存しないので、どんな開発環境でも同じように使える 伊藤 恒平 Claude Code ワークフロー 2 / 34
Claude Code とは 概要 Anthropic 社が提供するコーディングエージェント。ターミナルから Claude を呼び 出し、コードの読み書きからテスト・変更記録まで自律的に実行する 機能 指示書ファイル 記憶の永続化 計画モード Git 連携 自動化の仕組み ※ 各機能の詳細は後半で解説 説明 プロジェクトのルールを書いたファイルを毎回読む 会話で学んだことを次回以降も覚えている コードを書かずに調査・設計だけさせるモード 変更の記録・共有を自動で行う 繰り返す作業やチェックを自動実行 インストール: npm install -g @anthropic-ai/claude-code 起動: cd your-project && claude 伊藤 恒平 Claude Code ワークフロー 3 / 34
まず「何を作るか」を決める — 要件定義 AI に「いい感じに作って」は通じない 曖昧な指示 → AI が勝手に解釈 → 意図と違うものができる。 最初に「何を作るか」を具体的に言葉にすることが最も重要 要件を具体化する 3 ステップ 1. 目的: このプログラムは何のためにあるか?(1 文で) 2. 機能: 具体的に何ができればいいか?(箇条書き) 3. 制約: 使う言語・ライブラリ・動作環境は? 例: TODO アプリ 目的: コマンドラインでタスクを管理する 機能: 追加・一覧・完了・削除 制約: Python、外部ライブラリなし Tips: 要件が具体的なほど AI の出力品質が上がる。チュートリアルで実践します 伊藤 恒平 Claude Code ワークフロー 4 / 34
なぜ「計画」が必要か AI に自由にコードを書かせると何が起きるか 意図と違う設計で大量のファイルを変更 → 手戻りコスト大 テストなしで実装を進める → バグの発見が遅れる 既存コードの意図を誤解 → 動いていた機能が壊れる 解決策:「承認」ステップを挟む 1. AI に計画を出させる(コードは書かせない) 2. 人間が計画をレビューして承認/修正 3. 承認後に初めて実装を開始 原則:「考える」と「書く」を分離する。これが手戻りを防ぐ最大のコツ 伊藤 恒平 Claude Code ワークフロー 5 / 34
Plan Mode — 設計してから書く Plan Mode(計画モード)とは Shift+Tab キーで切り替え。コード編集をできない読み取り専用モード。AI に調 査・設計だけをさせ、方針が固まってから実装に移る 有効な場面 複数ファイルにまたがる変更 設計の判断が必要なとき 失敗コストが高い作業 初めて触るプロジェクト Plan Mode でできること ファイルを読んで調査する プロジェクトの構造を分析する 変更計画を作って提案する × ファイルの編集・作成 × コマンドの実行 Tips: 大きな変更ほど計画モードが効く。5 分の計画で 1 時間の手戻りを防げる 伊藤 恒平 Claude Code ワークフロー 6 / 34
Plan → Approve → Implement サイクル 修正依頼 Plan Mode で設計 ユーザーが 承認/修正 実装 (小さな単位) 失敗 次のタスク or 完了 変更を 記録 ビルド/テスト で検証 赤枠 = 人間の承認ポイント。ここで方向修正できるから安全に AI を使える。 Tips: 大きな変更はフェーズに分割して計画 → 各フェーズを独立してコミット・検証 伊藤 恒平 Claude Code ワークフロー 7 / 34
Plan Mode の実践例 例:「CSV を読み込んでグラフ表示する機能を追加して」→ 計画モードで出る計画: ## Plan: CSV 読 み 込 み + グ ラ フ 表 示 機 能 ### 変 更 対 象 フ ァ イ ル 1. src/csv_reader.py 2. src/plot.py 3. src/main.py 4. tests/test_csv.py ( 新 規 ) - CSV 読 み 込 み 処 理 (新 規) - グ ラ フ 描 画 処 理 (既 存) - メ ニュー に 項 目 追 加 (新 規) - 読 み 込 み の テ ス ト ### 設 計 判 断 - CSV ラ イ ブ ラ リ : 標 準 の csv モ ジ ュ ー ル を 使 用 - グ ラ フ 描 画 : matplotlib を 使 用 - ファ イ ル 選 択: コ マ ン ド ラ イ ン 引 数 で 指 定 ### 影 響 範 囲 - 既存の機能には影響なし - requirements.txt に matplotlib を 追 加 ユーザーが「3 ファイルに分けず 1 ファイルにまとめて」→ 計画を修正 → 承認 → 実装開始 Tips:「バグを直して」より「バグが起きない設計にして」と計画させる方が効果的 伊藤 恒平 Claude Code ワークフロー 8 / 34
なぜ Git(変更履歴の管理)が重要か AI がファイルを自律的に変更する世界では 変更履歴がなければ「何が変わったか」「なぜ変わったか」が追えない。 Git なしで AI にコードを書かせるのは、セーブなしでゲームをするようなもの Git が提供する安全網 Claude Code の Git 連携 Git = 変更履歴を記録・管理するツール 記録メッセージを自動作成 変更の差分を確認できる 統一された記録形式に準拠 いつでも前の状態に戻せる 変更の要約を自動生成 誰が何を変えたか記録される 原則: AI と協働するなら Git は必須。「こまめに記録」が最大の保険 伊藤 恒平 Claude Code ワークフロー 9 / 34
コミット戦略 コミット(変更の記録)のルールを決めておく 「何をなぜ変えたか」が伝わる記録を残す。Claude Code が自動でこの形式に従う: feat(csv): add CSV import and graph display ← 種 類 ( 範 囲 ): 変 更 の 要 約 ( 1 行 ) Changes: - CSV 読 み 込 み 処 理 を 実 装 ← 何を変えたか - matplotlib で グ ラ フ 描 画 機 能 を 追 加 Next steps: ← 次にやるべきこと - tests/test_csv.py で テ ス ト を 実 行 - 大 き な CSV フ ァ イ ル で の 動 作 確 認 記録するタイミング: 1 機能 = 1 記録(小さな単位で) Next steps(次の作業)の効果: 次回起動時の再開ポイントになる テスト成功後 コマンドレベルで具体的に書く 作業の区切り・中断時 AI が「前回の続き」を即座に把握 伊藤 恒平 Claude Code ワークフロー 10 / 34
GitHub 連携 — 変更をチームに共有する Pull Request(PR)=「この変更をレビューしてください」 という依頼 「この変更で PR を作成して」と Claude Code に指示するだけで: 1 変更内容を分析して説明文を自動生成 2 GitHub 上に PR(変更のレビュー依頼)を作成 3 チームメンバーのレビューコメントへの対応も可能 ブランチを 作成 実装 + 変更を記録 PR を作成 (レビュー依頼) チームが 確認 承認 → main に統合 Tips: Claude Code はレビューコメントを読んで修正も自動で作れる 伊藤 恒平 Claude Code ワークフロー 11 / 34
安全な運用 — main ブランチを直接触らない main(main)を直接変更しない Git では「main」と「ブランチ」を分けられる。AI に main を直接変更させると、レ ビューなしで反映されてしまう。必ずブランチ → レビュー → 統合の流れを守る 推奨フロー 1. ブランチを作成 2. その枝で実装・テスト・記録 3. レビュー依頼を作成 4. 確認・承認後に main へ統合 AI にやらせないことを決 める 設定ファイルで制御: main への直接書き込みをブロック 5. ブランチを削除 使えるコマンドを制限 GitHub 側でも main を保護できる 原則: AI に「何をさせるか」だけでなく「何をさせないか」も設定する 伊藤 恒平 Claude Code ワークフロー 12 / 34
CLAUDE.md — AI への指示書ファイル CLAUDE.md とは プロジェクトのフォルダに置くテキストファイル(CLAUDE.md) 。 Claude Code は起動するたびにこのファイルを最初に読む。 ここに書いたルールに AI が従うようになる 書くべき内容 ビルド・テストの実行コマンド コードの書き方のルール・変更記録の形式 やってはいけないこと(例:「このファイルは変更禁止」)← 最も効果が高い プロジェクトの構造の説明 重要: CLAUDE.md を書く = AI に知識を教える。ドキュメント化の手間が「AI の教育投資」として返ってくる。 ※ CLAUDE.md は人間が書く指示書。AI が自動で書き込むことはない 伊藤 恒平 Claude Code ワークフロー 13 / 34
Memory(MEMORY.md)— AI が自分で書く記憶ノート CLAUDE.md との違い 誰が書くか 何を書くか 保存場所 共有 CLAUDE.md 人間が書く プロジェクトのルール プロジェクト内(Git 管理) チームで共有できる MEMORY.md AI が自動で書く 会話で学んだこと PC のローカル この PC だけ MEMORY.md の仕組み Claude Code が会話中に「覚えておくべきこと」を見つけると自動で作成・更新する MEMORY.md はメモリファイルへの索引(200 行制限あり) 実際の記憶内容は個別のファイルに保存され、索引からリンクされる 「これを覚えて」と明示的に指示することもできる 注意: Memory はローカル専用 → 別 PC やチームメンバーには引き継がれない。 伊藤 恒平 Claude Code ワークフロー 14 / 34
Claude Code にとっての「知識」とは Claude Code は毎回まっさらな状態で起動する 前回の会話は覚えていない。ではどうやってルールを知るのか? → ファイルに書 かれた情報を毎回読み込むことで知識を得る 知識の種類 具体例 プロジェクトのルール 「テストは pytest で実行」 「変更記録は英語で書く」 過去の失敗から学んだこと 「この関数は変更禁止」 ユーザーの好み 「説明は日本語で」「コメントは簡潔に」 カスタムコマンド /commit で自動記録 等 これらはすべてファイルとして保存されている。置き場所で「持ち運べるか」 「この PC だけか」が 変わる → 次ページ 伊藤 恒平 Claude Code ワークフロー 15 / 34
持ち運べる知識 vs この PC だけの知識 持ち運べる知識(Git 管理) この PC だけの知識(ロー プロジェクトのフォルダ内に保存。 カル) git clone すれば別 PC でも復元 ファイル CLAUDE.md ルールブック .claude/skills/ コマンド .claude/settings.json の設定 役割 プロジェクトの カスタム 権限・自動化 あなたの PC の中だけに保存。 別の PC には引き継がれない ファイル Memory 学んだこと グローバル CLAUDE.md 共通の個人設定 役割 過去の会話で 全プロジェクト 重要: Memory の大事なルールは CLAUDE.md にも書く → 持ち運べる知識になる 伊藤 恒平 Claude Code ワークフロー 16 / 34
git clone すれば AI の知識も一緒に来る 別の PC やチームメンバーへの共有 CLAUDE.md やカスタムコマンドは Git 管理。クローンすれば AI の知識も自動的 に手に入る git clone リポジトリを取得 CLAUDE.md を 自動で読み込み claude を起動 → 初日から AI がルールを理解 GitHub = AI の知識の共有拠点 新メンバーがクローン → 同じルールを即座に共有 指示書の改善をレビュー依頼で提案 → チームで AI ルールを議論 伊藤 恒平 Claude Code ワークフロー 17 / 34
Claude Code を育てる Claude Code を 使って開発 期待と違う 結果が出る 指示書に ルールを追加 さらに高度な タスクを任せる 次回から 自動的に改善 記憶機能で 学んだことを保存 成長サイクル 1 ヶ月目: ビルドコマンドと 3 ヶ月目: 失敗事例から構築された 基本規約だけの CLAUDE.md チェックリスト・禁止事項の集大成 実例: あるプロジェクトでは CLAUDE.md が 20 回以上更新され、チェック項目は 0 個→ 30 個以上に成長。 投資対効果: ドキュメント化の時間は「AI への教育投資」。使い込むほど賢くなる 伊藤 恒平 Claude Code ワークフロー 18 / 34
Hooks(フック)とは —「○○したら自動で△△する」 Hooks とは Claude Code が何か操作をする前後に、決めておいた処理を自動実行する仕組み。 例:「ファイルを書き換えたら自動でコード整形」/「危険なコマンドをブロック」 タイミング 操作の前 操作の後 通知時 応答完了後 何ができるか 危険な操作を事前にブロック コード整形・書式チェックを自動実行 長い処理の完了をデスクトップに通知 自動でテストを実行 Hooks はどこに設定するか ファイル .claude/settings.json settings.local.json ~/.claude/settings.json 伊藤 恒平 範囲 プロジェクト限定 プロジェクト + PC PC の全プロジェクト 共有 Git 管理 ローカル専用 ローカル専用 Claude Code ワークフロー 19 / 34
Hooks の活用例
例 1: 自動フォーマット
例 2: 危険コマンドブロック
ファイル編集後に自動で整形
実行前に危険な操作を止める
{
{
}
"hooks ": {
"PostToolUse ": [{
"matcher ": "Write|Edit",
"command ": "npx prettier
--write $TOOL_INPUT_PATH"
}]
}
}
"hooks ": {
"PreToolUse ": [{
"matcher ": "Bash",
"command ": "if echo
$TOOL_INPUT | grep -q
'rm -rf '; then
exit 2; fi"
}]
}
他の例: 完了通知(デスクトップ通知)/ 自動テスト(作業完了後に実行)/ コミット前チェック
伊藤 恒平
Claude Code ワークフロー
20 / 34
Skills(スキル)とは — 自分だけのコマンドを作る Skills とは 複雑な手順を /commit のような 1 コマンドで実行できる仕組み。 手順書ファイル(SKILL.md)をプロジェクト内に置いて定義する 手順書ファイルの中身 --name: commit description: ル ー ル に 従 っ て 変更を記録する allowed -tools: [Bash , Read] --1. 変 更 内 容 を 確 認 2. 記 録 メ ッ セ ー ジ 作 成 3. 変 更 を 記 録 Skills はどこに置くか 場所 .claude/skills/ (Git で共有) ~/.claude/skills/ プロジェクト共通 範囲 プロジェクト固有 この PC の全 組み込み: /commit 変更を記録 /simplify 品質チェック 伊藤 恒平 Claude Code ワークフロー 21 / 34
Subagent(サブエージェント)— AI の分身を使う Subagent とは Claude Code が別の AI を一時的に起動して作業を任せる仕組み。人間でいう「部 下に調査を頼む」ようなもの。本体は別の作業を続けられる 種類 汎用タイプ 調査タイプ 設計タイプ 何をさせるか 複雑な作業を丸ごと委任 コードを読んで構造を調べる(編集はしない) 変更計画を考える(編集はしない) 任せてよいこと メインで確認すべきこと 大量ファイルの検索・調査 テストの並列実行 設計判断・方針の決定 サブエージェントの「問題なし」 を鵜呑みにしない ビルドのバックグラウンド実行 最終的な品質の検証 伊藤 恒平 Claude Code ワークフロー 22 / 34
コンテキスト管理 コンテキスト(AI が一度に扱える情報量)には上限がある 会話が長くなると、AI は古い指示を忘れたり精度が落ちたりする。コンテキストを 上手に管理することが大事 対策 /compact(圧縮) サブエージェントに委任 Memory に保存 CLAUDE.md を簡潔に 説明 会話履歴を AI に要約させて短くする 大量の調査結果を本体に持ち込まない 毎回伝え直す情報は記憶ファイルに保存 毎回読むファイルなので短く保つ Tips: /compact で圧縮。大事な情報は Memory に保存しておけば圧縮後も残る 伊藤 恒平 Claude Code ワークフロー 23 / 34
初心者がやりがちな失敗 失敗パターン 計画なしでいきなり実装さ せる 変更履歴を管理しない 指示書ファイルを書かない main に直接変更を送る 自動化を使わず手作業を繰 り返す 記憶機能を活用しない 何が起きるか 意図と違う設計で大量変更 → やり 直し AI の変更を追えない → 戻せない 毎回同じ指示を繰り返す → 非効率 レビューなしで本番反映 → 障害リ スク 書式チェック忘れ・整形崩れが頻発 同じミスを何度も指摘する必要がある 共通の原因: AI を「魔法の箱」として扱ってしまう →対策: 安全装置(計画・変更管理・指示書)を先に整える 目安: fix が 3 回以上続いたら手を止めて Plan Mode に戻る(場当たり修正の連鎖を断つ) 伊藤 恒平 Claude Code ワークフロー 24 / 34
Top 10 Tips 1 2 3 4 5 6 7 8 9 10 計画してから書かせる — 5 分の計画で 1 時間の手戻りを防ぐ 変更は必ず Git で記録 — こまめに記録、Next steps を含める ブランチ → レビュー → main — main を直接触らない 指示書(CLAUDE.md)は AI への教育投資 — 書くほど賢くなる 「やるな」は「やれ」より効果的 — 禁止事項を明記する 記憶機能で同じミスを防ぐ — 一度伝えれば以降ずっと従う Claude Code を育てる — 失敗するたびにルールを追加 フック(Hooks)で自動化 — 手作業の繰り返しを排除 スキル(Skills)で 1 コマンドに — 複雑な手順をまとめる GitHub = AI の知識の共有拠点 — クローンすれば知識も一緒に来る 伊藤 恒平 Claude Code ワークフロー 25 / 34
参考資料 / はじめよう URL https://docs.anthropic. com/en/docs/claude-code ベストプラクティス https://docs.anthropic. com/en/docs/claude-code/ best-practices Claude Code GitHub https://github.com/ anthropics/claude-code リソース 公式ドキュメント Claude Code を始めるには npm install -g @anthropic-ai/claude-code cd your-project && claude 伊藤 恒平 Claude Code ワークフロー 26 / 34
チュートリアル: TODO アプリを作ろう 概要 Claude Code のワークフローを体験する実践演習。 コマンドライン TODO アプリ(Python)をゼロから完成させる Step 1 2 3 4 5 6 内容 インストールと初期設定 要件を定義する 計画を立てる 実装する バグを見つけて直す 振り返り 学ぶこと 環境構築、CLAUDE.md 作成 目的・機能・制約の言語化 Plan Mode の使い方 計画に基づく段階的な実装 テスト、デバッグ、コミット CLAUDE.md の改善サイクル 前提: Python 3 と Node.js がインストール済みであること 伊藤 恒平 Claude Code ワークフロー 27 / 34
Step 1: インストールと初期設定 Claude Code をインストールして、プロジェクトを準備 する # 1. Claude Code を イ ン ス ト ー ル npm install -g @anthropic -ai/claude -code # 2. プ ロ ジ ェ ク ト フ ォ ル ダ を 作 成 mkdir todo -app && cd todo -app # 3. Git リ ポ ジ ト リ を 初 期 化 git init # 4. Claude Code を 起 動 し て CLAUDE.md を 生 成 claude /init CLAUDE.md を編集して最初のルールを書く ## Build python todo.py ## Rules - Python 3 、 外 部 ラ イ ブ ラ リ な し - デ ー タ は todo.json に 保 存 伊藤 恒平 Claude Code ワークフロー 28 / 34
Step 2: 要件を Claude Code に伝える 目的・機能・制約を具体的に伝える Claude Code に以下のように入力する: コ マ ン ド ラ イ ン TODO ア プ リ を 作 り た い 。 目 的: ター ミ ナ ル で タ ス ク を 管 理 す る 機 能: - タ ス ク の 追 加 (add " タ ス ク 名 ") - 一 覧 表 示 (list) - 未 完 了 / 完 了 を 区 別 - 完 了 に す る (done 番 号 ) - 削 除 (delete 番 号 ) 制 約: - Python 3 、 外 部 ラ イ ブ ラ リ な し - デ ー タ は todo.json に 保 存 - 日本語対応 ま ず Plan Mode で 設 計 し て く だ さ い 。 ポイント:「まず Plan Mode で」と指示することで、いきなりコードを書かせない 伊藤 恒平 Claude Code ワークフロー 29 / 34
Step 3: 計画を確認して承認する Claude Code が計画を出す → 人間が確認 計画モードで以下のような出力が返ってくる: ## Plan: コ マ ン ド ラ イ ン TODO ア プ リ ### フ ァ イ ル 構 成 1. todo.py - メ イ ン 処 理 ( 引 数 解 析 、 CRUD 操 作 ) 2. todo.json - デー タ 保 存(自 動 生 成) ### 設 計 - argparse で add/list/done/delete を 処 理 - JSON フ ァ イ ル で デ ー タ 永 続 化 - 各 タ ス ク は {id , text , done} の 辞 書 確認ポイント: ファイル構成は妥当か? 設計は要件を満たすか? 問題なければ「OK、実装して」と承認。修正したければ「ファイルは 1 つにして」等 伊藤 恒平 Claude Code ワークフロー 30 / 34
Step 4: 実装してテストする 承認後、Claude Code が実装を開始する 実装が完了したら、自分で動かして確認: # タスクを追加 python todo.py add " 牛 乳 を 買 う " python todo.py add " レ ポ ー ト を 書 く " # 一覧表示 python todo.py list [ ] 1: 牛 乳 を 買 う [ ] 2: レ ポ ー ト を 書 く # 完了にする python todo.py done 1 # 再 度 一 覧 → 完 了 マー ク が つ く python todo.py list [x] 1: 牛 乳 を 買 う [ ] 2: レ ポ ー ト を 書 く 動いたらコミット:「ここまでコミットして」→ Claude Code が自動で記録 伊藤 恒平 Claude Code ワークフロー 31 / 34
Step 5: バグを見つけて修正する 意図的にバグを探してみる 以下を試して、おかしな動作がないか確認: # 存 在 し な い 番 号 を 完 了 に し た ら? python todo.py done 999 # 引 数 な し で 実 行 し た ら? python todo.py # 空 文 字 の タ ス ク を 追 加 し た ら? python todo.py add "" バグを Claude Code に修正させる Claude Code に伝える: done 999 で エ ラ ー に な る 。 存 在 し な い 番 号 に は エ ラー メッ セー ジ を 表 示 し て く だ さ い。 引 数 な し の 場 合 は ヘ ル プ を 表 示 し て く だ さ い。 伊藤 恒平 Claude Code ワークフロー 32 / 34
Step 6: 振り返り — CLAUDE.md を育てる チュートリアルで体験したワークフロー Step 1 2 3 4 5 6 やったこと 環境構築 要件定義 計画 実装 バグ修正 振り返り 対応する機能 claude /init で CLAUDE.md 作成 目的・機能・制約を言語化 Plan Mode で設計→承認 承認後にコード生成→テスト エラー報告→修正→コミット CLAUDE.md にルールを追加 次にやること: CLAUDE.md を改善する チュートリアルで気づいたことを CLAUDE.md に追記しよう: 例:「エラー処理は必ず入れること」「引数なしの場合はヘルプを表示」 → 次回から Claude Code が自動的にこのルールに従う = 育てる 伊藤 恒平 Claude Code ワークフロー 33 / 34
付録: Claude Code と Codex CLI(OpenAI)の違い どちらもローカルで動く CLI コーディングエージェント Codex CLI を使っている人向けに、主な違いを整理する。指示書ファイルの仕組み は共通点が多い 指示書ファイル 階層構造 (AGENTS.override.md で上書きも可) パス固有ルール パスごとにルールを分けられる 自動記憶 学習を記録。ローカル専用) 手動で編集する必要がある) 計画モード 自動化・拡張 権限管理 Claude Code CLAUDE.md グローバル → プロジェクト → サブディ レクトリ Codex CLI AGENTS.md(同じ役割) 同様の階層構造あり .claude/rules/*.md で なし(単一ファイル) MEMORY.md(AI が自動で なし(AGENTS.md を Plan Mode で設計→承認→実装 Hooks / Skills / MCP suggest / auto-edit / full-auto なし 限定的 suggest / auto-edit / full-auto 最大の違い: Claude Code は MEMORY.md で AI が自動的に学習を蓄積する。Codex CLI は AGENTS.md を人間が手動 で育てる必要がある 伊藤 恒平 Claude Code ワークフロー 34 / 34