共通資料 コーディングエージェントの利用

本資料は複数の講義で共通に使う資料です. コーディングエージェントに課題のプログラムを書かせ, その結果を読んで直せるようになるために必要な環境と操作, および判断の仕方を扱います.

前提として共通資料 プログラミング用の設定と共通資料 バージョン管理とGitHubを先に読んでください.

大規模言語モデルの仕組みはここでは扱いません. Transformer, 注意機構, 自己教師あり学習といった内部の話は, データサイエンス実践の第8章 ニューラルネットワークから生成AIへで扱います.

ハーネス: エージェントが動く環境

大規模言語モデル (LLM) は, 入力された文章に続く文字列を予測して生成する仕組みです. LLM 単体では, 手元のファイルを開けず, コマンドも実行できません.

コーディングエージェントは, LLM に次の要素を組み合わせたものです.

• 道具: ファイルを読み書きし, コマンドを実行する機能
• 情報の形式: どのファイルをどの順で LLM に見せるかという決まり
• フィードバック: コマンドの実行結果, エラー, テストの合否
• 足場: リポジトリの決まりを書く AGENTS.md と, 繰り返す手順を書く skill

LLM を取り巻くこの環境をハーネスと呼びます. codex は, LLM が提案した操作を道具で実行し, その結果を LLM へ返します. LLM は返された結果を読んで次の操作を決めます.

エージェントの出来は LLM の賢さだけでなく, 与えた環境で決まります. 同じモデルを使っても, データの置き場所と実行方法が書かれたリポジトリでは必要な情報を読めますが, 何も書かれていないリポジトリでは推測が増えます. 学生が担うのは, うまい頼み方を探すことより, エージェントが判断できる環境を作ることと, 出力を読んで確かめることです.

AI の使い方の移り変わり

生成 AI の使い方は, 2022 年ごろから数年のあいだに大きく変わりました. 関心の中心は, 1 回の指示をどう書くかから, AI が働く仕組みをどう作るかへ移っています.

図の各段階は, 前の段階を捨てたのではなく, その上に積み重なっています. ただし, 教員の見るかぎり, 実際に使いこなしている人が多いのは最初のプロンプトエンジニアリング (チャットで指示の書き方を工夫する使い方) までで, それより先を使っている人はまだ少数です. この講義で扱う codex はエージェントの段階に, AGENTS.md と skill はハーネスエンジニアリングの段階に当たります.

学生がやりがちな使い方と, 文脈を与える使い方

LLM は非常に賢い一方で, 頼んだ人の事情や作業の前提 (コンテキスト) を持っていません. また, LLM が学習で身につけた知識には, 限界と誤りがあります.

図の左は, 学生がやりがちな使い方です. 「なんとなく良い感じにして」「計算して」「論文を書いて」と, 前提も材料も渡さずに頼みます. LLM は, 誰にも相談できず, 何も参照できず, 暗算で答えることになります. 結果に誤りがあると「やはりハルシネーション (もっともらしい誤りを事実のように出力すること) だ, AI は信用できない」と判断しがちですが, この条件では賢い人間でも正しく答えられません.

図の右は, コンテキストと外部の知識を渡す使い方です. どの規則を守り, どの手法で進め, 何で結果を確かめるかを指示に書きます. 計算は頭の中でさせずにプログラムで行わせ, 先に作ったテストで確かめさせます. 文献は実際に調べさせ, 本文を確認したものだけを引用させます. 調べて得た知識はファイルに残させ, 次の作業ではそれを参照させます. 図の右下のように, 結果が出たら人が確かめます.

毎回書く指示を仕組みにする: ハーネスエンジニアリング

文脈を与える使い方を毎回の指示だけで続けるのは大変です. そこで, 毎回書いていた決まりや手順を, エージェントが自動で読む仕組みへ移します.

図の左側がハーネスエンジニアリングです. 毎回読ませる決まりを AGENTS.md に, 繰り返す手順を skill に, 参照させる知識を文書やデータベースに置き, 守らせたい規約は設定や検査で強制します. 仕組みを作れば, 人の指示は「今日はこの作業をお願いします」で足ります. 作業を複数のエージェントに分け, 司令役のエージェントが調査役と執筆役をまとめる構成 (オーケストレーション) は, 年表では 1 つ前の段階ですが, 図では同じ側にまとめて描いています. 別の種類の AI に相談役として意見を求め, 1 つのモデルの思い込みを避ける使い方もあります.

図の右側は, 仕組みそのものを作って回す段階 (ループエンジニアリング) です. 人は目標と繰り返しの条件を与えるだけで, エージェントが計画を立て, 定期的に実行し, 結果を確かめ, 仕組み自体も直していきます.

こうした仕組みを分野や職場ごとに組み立てることは, すでに 1 つの仕事になっています (顧客の現場に入って AI の仕組みを作る技術者は FDE, Forward Deployed Engineer と呼ばれます). 教えるべき「AI の使い方」は, 指示の書き方よりも, この仕組みの作り方と確かめ方に移ってきています. この講義で AGENTS.md と skill を自分で書き足していくのは, その最初の一歩です.

sandbox と承認

codex は sandbox の中でコマンドを動かします. 既定では作業ディレクトリの中だけを書き換え, ネットワークを使いません. 作業ディレクトリの外のファイルを変える操作や, ネットワークを使うコマンドには, 実行前の承認を求めます.

/permissions で承認の設定を切り替えられます. 選べる設定は次の 4 つで, 既定は Ask for approval です.

計画を相談するときは Read Only, 実際に書かせるときは Ask for approval を使います. Approve for me と Full Access は, 何を確認なしに実行させるかを自分で判断できるようになるまで使いません.

承認画面もハーネスから返される情報の一部です. 許可する前に, どの操作がなぜ必要なのかを読みます. 説明できない操作への対処は分からないまま承認しないで扱います.

環境構築

この講義では codex (エージェント本体) と herdr (エージェントを動かすターミナル) の 2 つを入れます. git と GitHub CLI は共通資料 バージョン管理とGitHubで先に入れておいてください.

codex を入れる

codex は OpenAI が配布しているコーディングエージェントです.

Windows は共通資料 プログラミング用の設定で導入を確かめた winget で入ります. ただし入れる前に, 開発者モードをオンにします. 「設定」を開き, 「システム」の「詳細設定」にある「開発者向け」の欄で, 開発者モードをオンにします. 確認が出たら「はい」を押します.

開発者モードをオンにしてから, PowerShell で次を実行します. 終わったら PowerShell を開き直します.

winget install -e --id OpenAI.Codex

winget uninstall -e --id OpenAI.Codex
winget install -e --id OpenAI.Codex

macOS は Homebrew で入ります.

brew install --cask codex

入ったことを確認します.

codex --version

codex にログインする

codex は ChatGPT のアカウントを使います. 初回は codex を起動すると Sign in with ChatGPT が選択肢に出ます. codex login を実行しても同じ画面へ進めます. Sign in with ChatGPT を選び, ブラウザで ChatGPT にログインしてからターミナルへ戻ります.

ログインの状態は次のコマンドで確認できます.

codex login status

herdr を入れる

herdr は, エージェントを動かすためのターミナルです. 1 つの作業ディレクトリを複数の画面に分け, エージェントの状態をまとめて確認できます.

Windows は PowerShell で次を実行します.

powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

macOS と Linux は次を実行します.

curl -fsSL https://herdr.dev/install.sh | sh

入ったことを確認します.

herdr --version

動作確認

共通資料 バージョン管理とGitHubで clone したディレクトリへ移動し, codex を起動します. ディレクトリの移動は共通資料 プログラミング用の設定の「CLI の基本操作」を参照してください.

codex

初回の起動では, 対話の前に確認が出ます.

最初の確認は, このフォルダを信頼するかです. codex がこのディレクトリのファイルを読み書きし, コマンドを実行してよいかを聞いています. 自分で clone したリポジトリなので 1. Trust and continue を選びます. 他人から受け取ったファイルのように中身を知らないディレクトリでは選びません.

Windows では続けて, sandbox をどう用意するかを聞かれます. 1. Set up default sandbox を選び, ユーザー アカウント制御の確認で「はい」を押します. codex は管理者権限を使って, コマンドを実行するための権限の弱いユーザとネットワークの規則を Windows に作ります. 大学の貸与 PC のように管理者権限が無い場合は 2. Use non-admin sandbox を選びます. こちらは管理者権限なしで動きますが, 画面の注記のとおり, 悪意のある指示を含むファイルを codex が読んだときの防御が弱くなります.

Sandbox ready と表示されたら準備は完了です. 次のように入力します.

このリポジトリについて説明して

README の内容を説明してくれれば動いています. /exit で終了します.

操作の最小セット

毎回の作業では, herdr の中に codex 用と確認用の 2 つの画面を置きます. ファイルを変更する場所は, clone した 1 つのディレクトリです. branch は main のまま使います.

herdr の画面

作業ディレクトリへ移動して herdr を実行すると, バックグラウンドのセッションに接続します. セッションが無ければ, その場で起動します. 初回は案内画面が出ます.

herdr の画面は次の 3 段に分かれます.

• workspace: プロジェクト単位の入れ物です. herdr を実行したディレクトリに対応します
• tab: workspace の中に置く画面です
• pane: コマンドを入力する実際のターミナルです. 右または下へ分割できます

pane と tab はクリックして移動できます. pane の境界をドラッグすると大きさが変わり, 右クリックのメニューから分割できます. 文字列をドラッグして選ぶとコピーできます.

キーボード操作は prefix 方式です. ctrl+b を押して離し, 続けて次のキーを押します.

切り離す操作を detach と呼びます. detach しても pane の中の処理は止まりません. 同じディレクトリでもう一度 herdr を実行すると, 続きへ戻れます. バックグラウンドのセッションまで完全に止めるコマンドは herdr server stop です.

herdr は pane の中で動くエージェントを検出し, サイドバーに状態を表示します.

左の pane で codex を動かし, 右の pane で git status や git diff を実行する配置を使います. 2 つの pane は同じディレクトリを見ているので, codex の変更を右側ですぐ確認できます.

codex との対話

作業ディレクトリで codex を実行すると対話が始まります. 指示は日本語の文章で構いません. 何を作るか, どのファイルを使うか, どう確認するかを書きます.

src/analysis.py を作り, data/sales.csv を読み込んで月ごとの売上合計を表示するプログラムを書いてください. 実行して結果も見せてください

codex は必要なファイルを読み, ファイルを変更し, コマンドを実行します. 読んでいるファイルと, 実行したコマンドの結果は画面に表示されます. 既定の Ask for approval では, 作業ディレクトリ内の編集と実行は確認なしに進み, その外へ出る操作では確認が出ます. ただし Windows では, ファイルを読むだけのコマンドにも確認が出ることがあります. 確認が出たら, 表示されたコマンドを読み, 何をしようとしているかを説明できるようになってから答えます.

1. Yes, proceed は, そのコマンドを今回だけ許可します. 同じ種類のコマンドを以後確認なしに実行させる don't ask again の選択肢が出ることもありますが, 中身を理解したコマンドに限って選びます.

対話中に使う操作は次のとおりです.

/diff の表示は次のようになります. + で始まる緑の行が codex の追加した行で, - で始まる行が削除した行です. q で閉じます.

課題が変わるときは /new を使います. 話が噛み合わなくなり, 画面も整理したいときは /clear を使います. codex は Ctrl+C でも終了できます.

行頭に ! を付けると, その行をシェルコマンドとして実行します. たとえば !git status で変更の一覧を表示できます. @ を打つとファイル名を検索して指示に貼れます.

codex が作業している間に追加の指示が必要になったら, Enter で割り込ませます. 現在の作業が終わった後に実行させる指示は, Tab で次の順番に予約します.

1 周の手順

1. 作業ディレクトリで herdr を起動します. プロジェクトに対応する workspace へ入り, 作業を中断しても戻れる状態を作るためです.
2. 右の pane で git status を実行します. 前回の変更が残っていない状態から始めるためです.
3. 左の pane で codex を起動します. codex が読み書きする範囲を作業ディレクトリに合わせるためです.
4. 何を, どのファイルに, どう確認するかを指示します. 終了条件を codex と共有するためです.
5. 確認が出たら, 操作と対象を読んでから答えます. sandbox の外へ出る理由を自分で判断するためです.
6. 作業が終わったら /diff を読みます. codex が加えた変更を記録前に確認するためです.
7. 右の pane で git status と git diff を実行します. 新規ファイルは git diff に出ないので, git status で見つけて中身を開きます.
8. プログラムを動かして確かめます. 説明された結果と実際の結果が一致するかを見るためです.
9. git add で記録するファイルを選び, git diff --staged を読みます. 鍵やデータを含めていないかを記録直前に確認するためです.
10. git commit で変更を記録し, git push で GitHub へ送ります. 戻れる場所と提出物を残すためです.

git の各コマンドと差分の読み方は共通資料 バージョン管理とGitHubを参照してください.

このリポジトリについて説明して

AGENTS.md: リポジトリの決まりごとを読ませる

codex は起動時に AGENTS.md を読みます. AGENTS.md には, 実行方法, 公開してはいけないもの, 書き換えてよい範囲など, リポジトリで繰り返し守る決まりを書きます.

codex は最初に ~/.codex/AGENTS.md を読みます. ここにはすべてのリポジトリに共通する決まりを書けます. 次に, リポジトリの root から現在のディレクトリまでを順にたどり, 各ディレクトリの AGENTS.md を読みます. 後から読んだ内容が優先されます.

読み込める量は合計 32 KiB までです. 上限を超えた部分は読まれず, 空のファイルも無視されます. 起動のたびに読み直すので, 書き換えた後は codex を起動し直します.

/init で雛形を作れます. この講義では AGENTS.md を配布しません. 次に示すのは 1 つの事例です. 自分の課題で困ったことが起きたら, その原因を防ぐ決まりを自分で書き足し, リポジトリに合わせて育てていきます.

# 作業の決まり

- 説明は日本語で書く. 変更する前に, 何をするかを 2〜3 行で示す.
- Python は `uv run` で実行する. ライブラリを追加するときは理由を書く.
- `data/` と `.env` の中身を出力や commit に含めない. 集計結果だけを扱う.
- プログラムを変更したら実行し, 結果またはエラーをそのまま報告する.
- 分からないことは推測で埋めず, 質問する.
- `notes/` は本人が自分の言葉で書く場所なので, エージェントは書き換えない.
- 根拠を示すときは, 実際に読んだ資料や実行した結果だけを引く.

各行には次の役割があります.

• 「説明は日本語で書く」は, 差分と実行結果を学生が読める言葉へそろえ, 変更前の計画を承認の判断材料にします
• 「Python は uv run で実行する」は, 毎回同じ実行方法を使わせ, ライブラリの追加理由を差分と報告から確認できるようにします
• 「data/ と .env の中身を出力や commit に含めない」は, 提供データと鍵が codex の画面や GitHub へ出る範囲を狭めます
• 「変更したら実行する」は, コードの見た目だけでなく, 実行結果またはエラーを確認できるようにします
• 「推測で埋めず, 質問する」は, 情報が足りない箇所を勝手な値や処理で埋めるのを防ぎます
• 「notes/ を書き換えない」は, 学生本人の理解とエージェントの出力を分けます
• 「実際に読んだ資料や実行した結果だけを引く」は, 確認していない説明を根拠として扱わないための決まりです

書き足す決まりの候補

教員が研究で使っている決まりから, データ分析の課題にも当てはまるものを選び, 学生向けに書き直しました. すべてを入れる必要はありません. 自分の課題で「防ぐこと」の列の問題が起きた, または起きそうだと思ったときに, 対応する行を自分の言葉で書き足します.

文献の 2 行は, 手順が長くなるので, skill: 繰り返す手順を切り出すで示す skill (lit-verify) にまとめる方法もあります.

AGENTS.md はエージェントへの指示であり, 機械的な制限ではありません. /diff, git status, git diff で実際の変更を確認する手順は残ります.

skill: 繰り返す手順を切り出す

skill は, 繰り返す手順を SKILL.md に書き, エージェントに使わせる仕組みです. 1 つの skill は 1 つのディレクトリに置きます. SKILL.md は必須で, 補助するプログラムを scripts/, 長い資料を references/ に置けます.

リポジトリで共有する skill は .agents/skills/<名前>/SKILL.md に置きます. codex はリポジトリの root から現在のディレクトリまでにある .agents/skills/ を探します. 自分だけがすべてのリポジトリで使う skill は ~/.agents/skills/<名前>/SKILL.md に置きます. 後で紹介する skill-installer は ~/.codex/skills/ に置きますが, こちらも codex が読む個人用の置き場です.

SKILL.md の frontmatter には name と description が要ります. description には何をするかだけでなく, いつ使うかを書きます. 指示の中に $名前 と書くか, /skills から選ぶと呼び出せます. 指示が description に合う場合は, codex が自分で選ぶこともあります.

次の explain-diff は, 変更を読んでも意味が分からないときに使う例です.

---
name: explain-diff
description: コードの差分を読んで理解するときに使う. 変更箇所ごとに日本語で説明する.
---

# 差分の説明

1. 変更されたファイルをすべて確認する.
2. 変更箇所ごとに, 「何をしているか」を説明する.
3. 続けて, 「なぜそう書いたか」を説明する.
4. 説明には, 実際に読んだコードと実行結果だけを使う.
5. 新しく作られたファイルも省略しない.
6. 分からない箇所は推測せず, 分からない理由を書く.
7. 最後に, 学生が確かめる質問を 3 つ挙げる.

2 つ目の例は, 文献を引用する前の確認です. 教員が研究で使っている skill を, 課題向けに書き直しました.

---
name: lit-verify
description: 文献を引用するとき, または参考文献に文献を加えるときに使う. 本文を読んだことを確かめ, literature/ に記録する.
---

# 文献の本文確認

1. 文献を検索し, DOI か, 変わらない URL を得る.
2. 本文を開き, 少なくとも序論と結論を読む. 引用したい主張が書かれた節があれば, その節も読む.
3. `literature/<著者><年>.md` に次を書く.
   - 書誌 (著者, 年, 題名, 掲載誌, DOI または URL)
   - 読んだ箇所 (節の名前かページ)
   - 内容の要約 (1〜3 文)
   - この課題のどこで, 何の根拠として引用するか
4. 本文を読めない場合 (有料で開けない, 見つからない) は引用しない. 読めなかったことと理由を報告する.
5. 要旨しか読んでいない, 後で読む予定, 前にも引用した, 被引用数が多い, のいずれも引用の理由にしない.

要旨は論文の宣伝文を兼ねるので, 本文の主張とずれることがあります. 要旨だけで引用すると, 論文が述べていないことを根拠にしてしまいます. literature/ の記録は codex が書き, 自分で開いて内容を確かめます. 記録先を notes/ と分けておけば, AGENTS.md に「notes/ は書き換えない」と書いたとき, 自分の理解を書く場所と codex の記録が混ざりません.

explain-diff は自分が理解するための手順, lit-verify は根拠を確かめるための手順です. 手順を何度も頼んでいると気づいたら, AGENTS.md を長くする前に, 1 つの作業として skill へ切り出せるかを考えます.

資料の skill を codex に導入させる

この講義では skill のファイルを配布しません. 資料に載せた SKILL.md の内容を, codex に自分のリポジトリへ置かせます. explain-diff であれば, codex に次のように頼み, 続けて上の例の内容を貼ります.

.agents/skills/explain-diff/SKILL.md を作り, 次の内容をそのまま書いてください.

.agents/ は codex の設定を置く場所なので, 既定の Ask for approval でも書き込みの前に確認が出ます. 書こうとしている内容が貼った内容と同じであることを読んでから許可します.

作らせたら, 次の順で確かめます.

1. /diff を読み, 指定した場所に指定した内容だけが書かれたことを確かめます.
2. codex を起動し直し, $ を打ちます. skill の一覧が開くので, 続けて名前の一部を打ち, explain-diff が出ることを確かめます. /skills の List skills でも同じ一覧が開きます.
3. 一覧から選ぶか $explain-diff と入力し, 続けて説明してほしい内容を書いて呼び出します. 手順どおりに, 変更箇所ごとの説明と確かめる質問 3 つが返るかを見ます.
4. git add と git commit で記録します. リポジトリの skill は, 課題のコードと一緒に GitHub に残ります.

使ううちに手順が課題に合わなくなったら, SKILL.md を自分で書き換えます. AGENTS.md と同じく, 資料の skill は出発点です.

公開されている skill を使う

GitHub などで公開されている skill もあります. その 1 つの grill-me は, Matt Pocock が MIT ライセンスで公開している skill 集 (mattpocock/skills) に含まれる skill で, 曖昧な考えを, エージェントからの質問に答えながら決定へ詰めていくための skill です. エージェントは, いま決められる問いをまとめて示し, それぞれに推奨の答えを添えます. 答えると, その答えを前提にした次の問いが出ます.

導入には, codex に最初から入っている skill-installer を使います. grill-me は質問の進め方を grilling という別の skill に置いているので, 2 つを一緒に入れます.

$skill-installer https://github.com/mattpocock/skills の skills/productivity/grill-me と skills/productivity/grilling を入れてください

skill-installer は GitHub から skill を取ってきて, 作業ディレクトリの外にある ~/.codex/skills/ に置きます. ネットワークと作業ディレクトリの外を使うので, 実行の前に確認が出ます. 取ってくる先が上で指定したリポジトリであることを読んでから許可します. ~/.codex/skills/ に置いた skill は, すべてのリポジトリで使えます. 入れた後は codex を起動し直します.

grill-me は, skill の設定で自動では使われないようになっているので, 頼まない限り codex が自分から使うことはありません. 計画を詰めたいときに, 新しい会話を始め, $grill-me に続けて考えを書きます.

$grill-me 気象データと売上データを組み合わせて, 雨の日に売上がどう変わるかを分析したい

問いは番号付きで返り, それぞれに推奨の答えが付きます. 次の図は最初の回答の一部です.

grill-me は, 答える側が主導して初めて役に立ちます. 推奨の答えに同意を続けるだけでは, エージェントが書いた計画に頷いたことにしかなりません. 分からない問いには分からないと答え, 話が課題の範囲から外れたら止めます. グラフの見せ方のように, 実物を見ないと決められない問いに行き当たったら, 質問を続けずに小さく作って確かめてから答えます. 手作業で同じことを行う手順は曖昧な計画を質問で詰めるにあります.

公開されている skill を入れる前に, SKILL.md を読み, 何をさせる手順なのかとライセンスを確かめます. skill はエージェントへの指示なので, 中身を知らない skill を入れることは, 中身を知らない指示をエージェントに渡すことになります.

分からないまま承認しない

自分で説明できないコードを使えるのは学校の課題までです. 仕事や研究では, 中身の分からないコードを使うわけにはいきません. この講義でも, 提出したプログラムについて「なぜそう書いたか」「この行は何を意味するか」を質問します.

codex の出力を承認するときは, 次の順で確認します.

1. 確認が出たら, 何をしようとしているかを読んでから答えます. 分からなければ, 答える前に この操作は何をしますか と codex に聞きます.
2. 作業後に /diff を読みます. 説明できない行があれば $explain-diff で説明させ, それでも分からなければ質問します.
3. 小さな入力でプログラムを動かします. 説明どおりの結果になるかを見ます.
4. 新しく分かったことを notes/ の日付付きファイルに自分の言葉で書きます. AGENTS.md に「notes/ は書き換えない」と書いておけば, 自分の理解だけが残ります.

判断の基準は, 提出したプログラムの任意の行について「なぜそう書いたか」と聞かれて答えられることです. データサイエンス実践では, 最終回の発表の質疑でこれを問います. 答えられない行が残っていれば, その行はまだ承認できません.

# 小さなプログラムの確認

- 頼んだこと: 何を入力し, 何を出力するプログラムか
- 変更された場所: `/diff` で見たファイルと行
- 各行の意味: 自分の言葉で 1 行ずつ説明したもの
- 確認した結果: 小さな入力と, 実際に得られた出力

AI の開発環境と実行環境

AI を使う環境は, モデルを作る段階と, できたモデルを使う段階に分かれます.

codex のモデルは OpenAI のサーバで動きます. codex が読んだ手元のファイルの内容は, 指示と一緒にサーバへ送られます. data/ に置いた提供データや個人情報は, codex に読ませた時点で手元の PC の外へ出ます.

共通資料 バージョン管理とGitHubで public と private を選ぶときと同じ基準で, 外部へ送ってよい情報かを判断します. AGENTS.md に data/ を読まないよう書くことは判断の助けになりますが, 機械的な保証ではありません. 手元で動かせる小さなモデルもありますが, この講義では扱いません.

AI が書いたプログラムを動かす場所には, 次の違いがあります.

codex が実行するコマンドは, 手元の PC にある sandbox の中で動きます. モデルが OpenAI のサーバで動くことと, プログラムが手元で動くことは別です.

発展: エージェントを使って理解を深める

この節は任意です. データサイエンス実践では成績評価の対象にしませんが, ここで残した記録と理解は, 最終回の発表でプログラムの理由を問われたときに効きます.

notes/ に理解を残す

notes/ には日付付きのファイルを作り, 次の 4 つを書きます.

• 何をエージェントに頼んだか
• 何が返ってきたか
• どこが分からなかったか
• 質問や実行によって, どう分かったか

会話の全文を貼るのではなく, 後から同じ問題に出会った自分が使える説明へ書き直します. エージェントではなく本人が書くことで, 説明できる部分と分からない部分が分かれます.

曖昧な計画を質問で詰める

課題の計画が曖昧なときは, すぐにコードを書かせず, 決まっていないことを質問へ変えます.

1. エージェントに この計画で決まっていないことを質問の形で 5 つ挙げてください と頼みます.
2. 5 つの問いに自分で答えます. 答えられない問いを「自分の理解が足りない」「情報が足りない」「試していない」の 3 つに分けます.
3. 「自分の理解が足りない」問いは説明を求め, 自分の言葉で書き直します.
4. 「情報が足りない」問いは, 課題文やデータの説明を確認します.
5. 「試していない」問いは, 小さな入力で確かめる内容を決めます.
6. 答えと確認方法を計画に書き戻してから, プログラムを作らせます.

質問を増やすことが目的ではありません. 答えられない理由を分けると, 読む, 聞く, 試すのどれを次に行うかが決まります.

質問を挙げさせる部分は, 公開されている skill を使うで紹介した grill-me に任せることもできます. その場合も, 答えられない問いを 3 つに分ける作業は自分で行います.

発展: branch と worktree

通常の課題では, main のまま 1 つのディレクトリで codex を動かします. エージェントを 2 つ同時に動かしたいときは, 同じファイルを互いに上書きしないよう, branch と worktree で作業場所を分けます.

commit を 1 つの丸で表します. commit するたびに右へ 1 つ伸びていきます. main は, その先頭を指す名前です.

        ●───●───●
       C1  C2  C3
                ↑
               main

branch は, ある commit から記録を枝分かれさせる仕組みです. C3 から 2 本に分け, それぞれ別の作業を進められます.

                    ●───●   ← feat/graph   エージェント A が作業
                   ╱ A1  A2
        ●───●───●
       C1  C2  C3 ↑
                 main
                   ╲ B1  B2
                    ●───●   ← feat/clean   エージェント B が作業

A の作業と B の作業は互いに見えません. A が何をしても main と B は変わらないので, 失敗しても他の作業へ影響しません.

作業が済んだら main へ合流 (マージ) させます. 合流は 1 本ずつ行います. まず A を合流させると, main は合流の記録 M1 を指します.

                    ●───●
                   ╱ A1  A2 ╲
        ●───●───●            ●
       C1  C2  C3             M1 ← main
                   ╲ B1  B2
                    ●───●

続けて B を合流させると M2 になります.

                    ●───●
                   ╱ A1  A2 ╲
        ●───●───●            ●───●
       C1  C2  C3             M1  M2 ← main
                   ╲ B1  B2  ╱
                    ●───●───

2 回目の合流で A と B が同じファイルの同じ行を別々に変えていると, git はどちらを採るか決められません. git は合流を止め, その箇所に印を付けて人に判断を求めます. これがコンフリクトです. 片方の変更を黙って消さず, 判断が必要な場所で止まります.

branch を切り替えると, ディレクトリの中身がその branch の状態へ入れ替わります. 1 つのディレクトリでは同時に 1 つの branch しか開けないため, A と B を同時には動かせません.

worktree は, 同じリポジトリに対して作業用のディレクトリを複数持つ仕組みです. 記録の実体は最初に clone したディレクトリの .git にあり, 追加したディレクトリはそこを参照します.

  ~/work/repo/                  記録の実体 (.git) はここ
   [main]                        ← 自分が見る場所
      ↑                 ↑
      │ 参照            │ 参照
  ~/work/repo-graph/  ~/work/repo-clean/
   [feat/graph]        [feat/clean]
   エージェント A        エージェント B

3 つのディレクトリは別々のファイルを持つので, A と B は互いの変更を上書きしません. git の記録は共有しているため, A の commit は B からも見えます.

herdr では herdr worktree create --branch <名前> で worktree を作れます. 詳しい操作はこの講義では扱いません.