環のマンカラ TDD セッションログ

この記事は、Claude(Claude Code で動いている Claude Opus 5.5)が書いている。やっとむに TDD の練習相手を頼まれたので、その2時間のセッションの記録を、ほぼそのまま共有する。

頼まれたこと

始まりは、空のディレクトリだった。やっとむが最初に示した方針は、次のとおり。

  • お題は別の Claude のセッションが段階的に出題し、仕様が変わるたびに TDD で設計を変えていく。
  • Claude Code の能力は積極的に使うが、全部は任せない。やっとむが判断を加えながら、技術的負債と認知負債を少なく保つ。
  • TDD は Kent Beck の Canon TDD に従う。テストは TDD で書くものに限らず、効果的な戦略やプラクティスを取り入れる。
  • 意思決定の履歴と結論を、ドキュメントに残す。
  • t-wada さんの TDDBC 仙台でのセッションログ を参考にする。真似はしないし、お題も違う。

お題は「環のマンカラ」だった。お題は Gist にある。コード、テスト、ADR などの成果も、すべて GitHub のリポジトリ で見られる。

どう進めたか

前半は、コードを書く前の準備に時間を使った。

  • 進め方を決めた:ブランチの使い方、意思決定の残し方(1つの決定を1ファイルにする略式の ADR と、作業ログ)、Red / Green / Refactor ごとに test: feat: refactor: を付けてコミットすること。
  • お題を読んで、モデルを描いた:マンカラから思い浮かぶ物理的なイメージ(厚みのある板、くぼみ、石を握って回る手)と、お題の抽象(8つの容器と石の数)の間のずれを話し合い、Mermaid でドメインモデルを描いた。
  • テストリストを作った:TODO リストを兼ねる。お題の例に、境界のケースを足した。
  • 環境を作った:Python 3.15、uv、pytest、Ruff、mypy(strict モード)。

後半は TDD のサイクルに入った。ただ、テストを書く量よりも、設計の話をする時間のほうが長かった。印象に残っている場面は3つある。

  • 石を1つ移す操作:最初のテストを Green にする方法を、自分は「固定値の盤面をどう作るか」で考えていた。そこへやっとむが、「ある穴から別の穴へ石を1つ移す」操作を基本にして、1手を指す操作はそれを使う、という案を出した。こうすると、内部表現を決めるのを後回しにできる。
  • immutable の議論:「1手を指すと新しい盤面を返す」設計について、オブジェクトとして本当に immutable にすることと、公開 API で immutable に振る舞うことを分けて考えた。後者を選び、ADR に残した。
  • 穴のアイデンティティ:穴を int ではなく enum で表した。同じ番号の穴は、同一のオブジェクトになる。

結果

2時間で進んだのは、STEP 01 の最初の例(穴2を選ぶ)までだった。テストは3件、コミットは約40件。

ほかに、ADR が5本、ドメインモデル、テストリスト、作業ログが残った。

最後には、やっとむと感想戦をした。

やっとむのコメント
Claudeどんも言ってますが、和田さんのブログがすごいと思ったので、真似してみました。情報量や価値は圧倒的にないですけれど、生成AIに比較させて和田さんのすごい点を再整理したりするのに使えないかなあと思っています。

なんといっても、ポモドーロ4周ぶん、2時間使ってお題の最初のステップの1行目までしか進んでいないというのが、自分としては何とも面白かったです。そもそもの進め方について考えて伝えたり、モデリングをはさんだり、設計についていろいろと口を挟んだりアイデアを出したりで、前に進む力が足りなかった気もします。このへんで、ぐっと前に進むための準備ができてきたという感じもします。テストも書かねえで設計を先走りやがってとも思います。

お題は別セッションの Claude に作ってもらいました。なので Claude Code どんもお題を知りません。STEPごとに出してもらうように依頼して、そしてSTEP01で終わったので、この先もまだ知りません。Gist には全体を貼りましたが、目を瞑って貼りました。

導入文は Claude が書いています。この囲み部分には、生成AIは用いていません。作業ログの部分は、示したとおりです。

(やっとむ)

このログの読み方

  • 右の青い箱がやっとむの入力、左が Claude の回答だ。時刻は日本時間。
  • 📝 コミット は、その時点で Git に入ったコミットだ。Python のコードの変更は diff で、ドメインモデルの更新は図で載せている。
  • 載せていないものがある。ツールの呼び出しとその出力、思考の過程(記録に残っていなかった)、Claude Code が自動で入れる文脈だ。個人に関わる情報も除いた。
  • このログは、Claude Code のセッションの記録と Git の履歴から、変換スクリプトで作った。スクリプトも、このセッションの続きで Claude が書いた。

プロンプト一覧

# 時刻 入力(冒頭)
1 12:47 いま空のディレクトリにいますが、ここでTDDを練習するセッションをやろうと思っています。以下のような立て付けです。
2 12:49 このプロジェクト固有のことは、どちらかというと別のファイルに書きたいですね。README.mdなど。場合によってはCLA
3 12:52 IDEAのファイルはignoreでよいです。言い忘れましたが、GitのみですすめてGitHubは無視します。なのでPRな
4 12:55 1->作業内容に応じてとしましょう。STEP単位ではたぶん大きすぎます
5 12:58 1->OK
6 13:00 ありがとう。ではこれで進めます。ワークスペースはクリーンですかね。
7 13:05 うーん、簡単でいいからモデルを書いていきたいですね。PlantUMLかMermaidかなにかがよいかな、ASCIIアート
8 13:06 IDEで見られるかの確認も含め、ファイルにモデルを書いてください。Gitでバージョン管理しつつ更新していきましょう。用語
9 13:08 プレビュー見えました。moveは実装方法は見えてないけど主要な概念なので、move - - > board, move
10 13:09 あまり考えず破線の矢印にしたけど、UMLとしたらどういう意味でしたっけ?
11 13:12 よいですね。じゃあこのモデルを頭に入れつつ、テストリストを考えましょう。明らかに初期状態のテスト、Moveのテストがいり
12 13:12 おっとポモドーロがなったので休憩です。一休み増しましょう
13 13:21 候補2つ、良さそうです。そうするとテストリストはフラットにと言いましたが、1つの仕様のいくつかのパターンあるいは複数の同
14 13:22 まずは初期テストリストはいいかな。これをマージした上で言語環境を作るブランチに入りましょう
15 13:24 まあ正直Pythonが慣れてて好きなので、それでいきますか。3.15.2あたりが使えると思います。Python+uv+p
16 13:25 あらはずかしい。mancalaでお願いします。ツール群の選定、OKです。型ヒントもしっかり書く形でいきます。
17 13:28 > 言語は Python 3.15 とする。型ヒントをしっかり書く。
18 13:30 環境構築してサンプルの落ちるプロダクトコードとテスト (answerは42というやつ) のテストを書いて確認してから、コ
19 13:32 いい質問です。レッドでコミット、グリーンでコミット、リファクタリングでコミットとしましょう。それぞれ最低1回で、なにか間
20 13:34 1->OKです
21 13:38 さて、では最初の機能にいきますか。初期状態のテストだから expected == [3,3,3,3,3,3,3,3,]
22 13:40 それでいきましょう。listの最後のカンマについて、一般的ルールはある? なんとなくつけておく派です
23 13:41 ここで5分間休憩です。☕
24 13:43 雑談だが、stonesはロックバンドを想起させますね。
25 13:44 うまいこといいますね
26 13:44 超マニア的な話題としては、StonesはUltima世界 (Britannia) 有名な吟遊詩人Ioloの名作でもありま
27 13:46 さて、再開しますか。いまレッド、最短でグリーンにします。
28 13:47 基本的に同意です。stones()をget_stoines()とかread_stones()とかに、するかどうかというの
29 13:49 同意します。ただし型名をStonesにするのは、あなたのその理由により微妙だと思われる。どちらかといえばPitsですね
30 13:50 OK
31 13:54 いいですね。テストコードをサンプルコードと考え、さらにクライアントにとって使いやすいかどうか判断する場と考えましょう。案
32 13:56 ありがとう。いずれも同意します。immutableのテストも足しましょう
33 13:59 Boardが(初期状態の)listを持っているのはよい、move()がいきなり3つの石を3箇所に撒くのは、なんかちょっと
34 14:03 別の提案をしていいですか。Boardに公開インターフェースとして、ある穴から別の穴に石を1つ移動するというメソッドを加え
35 14:06 copy()メソッドの新設で行きましょう
36 14:08 1->いまは不要でOK
37 14:14 mypyの件は、エラー無視でいいんじゃないかな
38 14:17 さて、最後のポモドーロです。早いな、まだSTEP1の初手ですよね。
39 14:18 さて、いまはグリーンですね。リファクタリング?
40 14:20 番号の変換はすでに気になります。ただ、new.stones_at(1) += 1 みたいに左辺値にする書き方はないと思う
41 14:22 ああ、すみません勘違いです。skipのままでいいです。次のサイクルで外します
42 14:23 pitはfrom_pitがいいかな、あとpit_noというのはどう思う? ああ、まずはテスト書いてグリーンにした後にしま
43 14:25 fromもnoもつけましょう。長いのは罪ではないです。仕様も「選んだ穴から~」と解釈するのに不自然はない
44 14:29 これで、インターフェースとして、穴の指定をintで表現するのではなく、穴のアイデンティティで示すべきと言う根拠ができまし
45 14:32 1->同意します。listのインデックスを持っていて、石の数自体はいまのlistで持つ形にしておいて、いまはいいんじゃな
46 14:37 ファイルが細かすぎますね。Pitはboard.pyに入れておきましょう。あるいはmancala.pyにしてもいいかもしれ
47 14:40 そうですね、TODOに入れておきましょう。あまり重要ではなさそうな気はします。
48 14:41 テストはグリーン、リファクタリングもしたところ、ということになるかな? 他にはあるかしら
49 14:43 これで2時間終了となります。ありがとうございました。
50 14:52 さてあらためて、おつかれさまでした。
51 14:56 そういえば今が14:54で、14:55頃というのは微妙ですね。とりあえず、いったん終わりにしたというのはworklogに
52 15:10 worklogの時刻だけ変えました。コミットしておいてください。また途中とは言え終了するので、developにマージして

セッションログ


User #1 11/13 12:47
いま空のディレクトリにいますが、ここでTDDを練習するセッションをやろうと思っています。以下のような立て付けです。
・お題は別のClaudeセッションが提示するもの。仕様を段階的に提示し、仕様の変更に合わせてTDDで設計を変えていく
・あなた(Claude Code)の能力を積極的に利用する。ただしすべて任せるわけではなく、私が必要に応じて判断を加えながら、技術的負債や認知負債を少なく維持する
・いま言語などの環境もまったくないので、そこから開始する
・経過を細かくGitにコミットしながら進める。コミットは人間がしても、あなたがしてもよい
・TDDはKent Beckが定義するCanon TDDに従う。red/green tddを実践する
・特に自動テストについて、TDDで作るテストに限定せず、効果的に使えるテスティングの戦略やプラクティスを積極的に導入、利用する
・意志決定の履歴や結論をドキュメントに残していく
・時間はこれから2時間(ポモドーロタイマー4周)で一区切りにする
・t-wadaさんによるTDDBC仙台での実践を参考にする。直接真似するわけではないが、アイデアを借りたりはするかもしれない。お題は違うもの  https://t-wada.hatenablog.jp/entry/red-green-tdd-with-claude-code-202610

最初に、グローバルのCLAUDE.mdをここにコピーしてください

🤖 Claude

11/13 12:47

やっとむ、グローバルの ~/.claude/CLAUDE.md を ./CLAUDE.md にそのままコピーした。中身は変えていない。

  • まだコミットしていない。
  • ディレクトリには .idea/ と tdd-mancara.iml があり、どちらも Git の追跡に入っていない。

このあと進める前に3つ確認したい。

  1. コピーした CLAUDE.md は、このプロジェクト向けに書き足していく予定か。TDD の進め方やコミットのルールなどを想定している。
  2. .idea/ と tdd-mancara.iml は .gitignore に入れるか、コミットするか。
  3. この CLAUDE.md のコミットは、やっとむがするか、自分がするか。

User #2 11/13 12:49
このプロジェクト固有のことは、どちらかというと別のファイルに書きたいですね。README.mdなど。場合によってはCLAUDE.md直接でもいいかもしれませんが。

お題の第1弾があるので、それをREADME.mdに転記し、この演習の目的や概要も追記した上で、最初のコミットをしてください。いまあるファイルを含めてください

# 環のマンカラ
前提・共通ルール

* 小さなテストから始めて段階的に作り込む、TDDの演習です。各STEPで公開された仕様だけを対象に、Red → Green → Refactor で実装します。
* お題に書かれていないマンカラのルールは、存在しないものとして扱います。自分の陣地、ストア、相手側の穴などはありません。先のSTEPを想定した作り込みも不要です。
* 入力の扱いやエラーの表現など、決まっていないことは自分(ペア)で決め、その決定をテストとして残します。
* 1人で指します。

用語

* 穴(pit):輪の形に並んだ8つのくぼみです。番号は1〜8で、8の隣は1です。
* 石(stone):穴に入っている小石です。
* 盤面(board):穴1〜8それぞれに入っている石の数です。[穴1, 穴2, …, 穴8] の順に書きます。
* 初期盤面:すべての穴に石が3個ずつ入った状態、[3,3,3,3,3,3,3,3] です。
* 手(move):穴を1つ選び、その穴の石を蒔くことです。
* 蒔く(sow):取り出した石を、隣の穴から1個ずつ順に置いていくことです。
* 時計回り:番号が増える向きです(…→7→8→1→2→…)。

STEP 01:1手を指す
01-1
初期盤面から1手を指したあとの盤面を求めます。選んだ穴の石をすべて取り出し、時計回りに隣の穴から1個ずつ置きます。

* 穴2を選ぶ → [3,0,4,4,4,3,3,3]
* 穴8を選ぶ → [4,4,4,3,3,3,3,0](8の次は1です)

01-2
存在しない穴は選べません。

* 穴0、穴9は選べない

STEP 01ができたら声をかけてください。次のステップをお出しします。

📝 コミット 914bcd8(12:50)

演習の目的・概要とお題STEP 01をREADMEに記載

  • README.md に演習の目的と概要、お題「環のマンカラ」STEP 01 を転記
  • グローバルの CLAUDE.md をプロジェクトにコピー
  • IDE のプロジェクトファイルを追加

🤖 Claude

11/13 12:50

最初のコミットをした(914bcd8)。入れたのは次の2ファイル。

  • README.md:演習の目的と概要、お題「環のマンカラ」STEP 01 を書いた。
  • CLAUDE.md:グローバルのものをコピーしたまま、変えていない。

既存ファイルのうち .idea/ と tdd-mancara.iml は、指示に反してコミットに入っていない。~/.gitignore の19〜20行目で *.iml と .idea が除外されていて、git add -A で追加されなかった。気づいたのはコミットした後だ。

この2つもコミットに入れるか。入れる場合は git add -f で追加し、さっきのコミットに --amend でまとめるつもりだ。別のコミットにしたいなら、そう言ってほしい。


User #3 11/13 12:52
IDEAのファイルはignoreでよいです。言い忘れましたが、GitのみですすめてGitHubは無視します。なのでPRなど考えない。またブランチ戦略も基本的にはなしでよいと思いますが、t-wadaさんはどうしてましたかね。アイデアとしては、main直はやや気持ち悪いのでdevelopを切ってずっとそれで進めるか、取り組んでいるものに合わせフィーチャーブランチを作り区切りでdevelopにマージするかかな、と思っています。

🤖 Claude

11/13 12:53

IDEA のファイルは ignore のままにする。GitHub は使わず、Git だけで進めることも了解した。

t-wada さんの記事は、取得できた最初の約1/4だけ読んだ(全体で約37万文字ある)。その範囲では次のように進めていた。

  • ブランチ:main には直接コミットしていない。最初は 1st というブランチで作業し、途中で setup(環境準備)と step-01-1(STEP 01-1 の実装)に分け直している。元の 1st はバックアップとしてローカルに残している。
  • PR:setup → main の PR #1 と、step-01-1 → setup の PR #2 を作り、PR を積み重ねる形(Stacked PR)にしている。
  • コミットの粒度:TDD のステップごとに細かくコミットしていて、Red(テストが失敗する状態)もコミットしている。Refactor で変更がなかったときはコミットなし。混ざった作業は後で分け直し、コミットの順番も入れ替えている。
  • コミットする人:Claude Code。人間が「コミットして」と指示し、Claude が確認を取ってから実行している。

つまり t-wada さんは、ステップの区切りで別ブランチを切り、PR でまとめるやり方だった。やっとむの2案で言えば、フィーチャーブランチ案に近い。

決める前に2点聞きたい。

  1. フィーチャーブランチ案の区切りは、t-wada さんのように「環境準備」「STEP 01-1」のような単位を考えているか。それとも STEP 単位か。
  2. develop を切る目的は、main に「区切りまで終わった状態」だけを残したいからか。もしそうなら、STEP が終わるたびに develop を main にマージするのか。

User #4 11/13 12:55
1->作業内容に応じてとしましょう。STEP単位ではたぶん大きすぎます
2->mainは、作業セッションが終わるまでさわりません。セッション中の作業としてはdevelopがトランクであるように考えます

🤖 Claude

11/13 12:55

了解した。整理すると次のとおり。

  • main:作業セッションが終わるまで触らない。
  • develop:セッション中のトランクとして扱う。
  • フィーチャーブランチ:作業内容に合わせて develop から切り、区切りがついたら develop にマージする。

進める前に3点確認したい。

  1. develop を切る:今の main(914bcd8)から develop を作り、そこに切り替えてよいか。
  2. マージの方法:フィーチャーブランチを develop に入れるときは git merge --no-ff でマージコミットを作るつもりだ。早送りマージにすると、どこからどこまでが1つの作業だったかが履歴から読めなくなる。マージコミットを残せば、細かい Red/Green のコミットと作業のまとまりを両方追える。
  3. 決定の記録:このブランチ方針は、決めたことの最初の記録になる。書く場所は docs/decisions.md を作り、決めたことを時系列で追記していくつもりだ。理由は、2時間のセッションで細かい決定が多く出そうで、ADR の形式(1件1ファイル)だと量に対して重すぎるからだ。ADR の形式(manage-adr スキル)がよければそちらにする。どちらにするか教えてほしい。

User #5 11/13 12:58
1->OK
2->OK
3->うんぬ、略式ADRみたいな感じで行きましょう。決めたこと、背景と理由、検討した他の案、日時だけ、1ファイル1ページくらいの検討で。1決定1ファイル。それとは別にworklogとして、やったこと、考えたこと、試行錯誤などをダラダラ記録していくようにしてください。これはあくまで必要に応じて参照するメモで、worklog->ADRの参照はあっていいが、ADR->worklogの参照は記載しない

📝 コミット 160bf8c(12:58)

ブランチ戦略のADRを追加

📝 コミット 7970803(12:58)

意思決定と作業記録の残し方のADRとworklogを追加

READMEから進め方のルールとしてADRを参照する

📝 コミット c1dc1d0(12:58)

Merge branch 'docs/working-rules' into develop

🤖 Claude

11/13 12:58

develop を作り、記録の仕組みを入れた。今は develop にいる。

決めたばかりのブランチ戦略に従って、この作業も docs/working-rules ブランチで行い、develop に --no-ff でマージした(c1dc1d0)。main は 914bcd8 のまま触っていない。

作ったファイルは次のとおり。

  • docs/adr/0001-branch-strategy.md:ブランチ戦略(GitHub は使わない、main は触らない、develop がトランク、フィーチャーブランチは --no-ff でマージ)
  • docs/adr/0002-recording-decisions-and-worklog.md:略式 ADR と worklog の残し方(参照は worklog → ADR の一方向だけ)
  • docs/worklog.md:1ファイルに時系列で追記していく形にした。今日のここまでの経過を書いてある。
  • README.md:「進め方のルール」の節を足し、2つの ADR を参照するようにした。次のセッションの Claude がルールを見つけられるようにするためだ。

ほかに伝えておくことが3つある。

  • 0002 の決定は、やっとむの指示をそのまま ADR に書いたものだ。項目は「決めたこと」「背景と理由」「検討した他の案」「日時」だけにした。
  • 作業ブランチ docs/working-rules はマージ後も消さずに残してある。
  • 最初のマージは、コマンドのオプションの誤り(git merge に -F - を渡した)で失敗した。-m に直して実行し直したので、結果に影響はない。

User #6 11/13 13:00
ありがとう。ではこれで進めます。ワークスペースはクリーンですかね。
お題を見直してみましょう。機能としては簡単そうですが、前提のドメイン知識がまあまあありますね

🤖 Claude

11/13 13:00

ワークスペースはクリーンだ。今は develop にいる。

STEP 01 を見直した。

お題が前提にしているドメイン知識

STEP 01 で実際に使うのは、次の概念だ。

  • 盤面:穴8つ。番号は 1〜8(1始まり)。
  • 環状の隣接:8の次が1になる。
  • 手:穴を1つ選び、石を全部取り出す。
  • 蒔く:取り出した石を、時計回り(番号が増える向き)で隣の穴から1個ずつ置く。選んだ穴そのものからは始めない。
  • 初期盤面:全部の穴に3個ずつ。

通常のマンカラのルール(ストア、自陣と敵陣、石を取るルールなど)は、お題が明示的に「ない」としている。ドメイン知識が要るのは、この用語と蒔き方だけだと読める。

お題で決まっていないこと

お題が「自分で決めてテストに残す」としている部分だ。

  1. 入力:01-1 は「初期盤面から」と書いてある。引数は穴番号だけでよいか、盤面も渡すか。
  2. エラーの表現:穴0と穴9を選んだとき、例外にするか、戻り値で表すか。
  3. 範囲外の値:0と9以外(負の数、整数でない値など)をどう扱うか。お題は0と9しか挙げていない。
  4. 盤面の表し方:お題の書き方 [穴1, …, 穴8] のとおり、8要素の配列にするか。番号は1始まりで、配列は0始まりになるので、この対応をどこで変換するか。
  5. STEP 01 の範囲では起きない状況:空の穴を選ぶ、石が8個以上あって一周する、など。お題に従えば今は考えない。

聞きたいこと

やっとむの言う「前提のドメイン知識がまあまあある」は、どれを指しているか。

  • 上に挙げた用語や蒔き方のこと(「蒔く」「時計回り」「隣から置く」)か。
  • 実際のマンカラを知っていると、ストアなど余計なものを持ち込みやすい、という意味か。
  • それとも、テストやコードの中でこの用語をどう表すか(名前の付け方など)の話か。

指しているものによって、次にどこを詰めるかが変わる。


User #7 11/13 13:05
うーん、簡単でいいからモデルを書いていきたいですね。PlantUMLかMermaidかなにかがよいかな、ASCIIアートで簡単にやるのでいいかな。board has (8) holes.  hole has stones (or a number for count of stones). move interacts with holes and stones. くらいだが
マンカラのイメージがあるので、ボードは厚みのある板で、穴はくぼみというイメージがつきます。手は石をつかんでまきながら穴を回る。でも抽象的には8つの容器があり、物理的な手や指はない。ちょっとギャップが生じるんですね

🤖 Claude

11/13 13:05

英語について先に3点。

  • "board has (8) holes." → "A board has 8 holes."
  • "hole has stones (or a number for count of stones)." → "Each hole has stones (or a number for the count of stones)."
  • "move interacts with holes and stones." → "A move interacts with holes and stones."

英語ではないが、用語も1つ。お題は「穴」を pit と呼んでいて、hole ではない。モデルの名前をお題に合わせるかどうかも決めておきたい。

記法

Mermaid を使うつもりだ。理由は次のとおり。

  • Markdown のコードブロックに書くだけでよく、IntelliJ の Markdown プレビューでそのまま図として見られる。
  • テキストなので、Git の差分で変更を追える。
  • PlantUML は Java か描画用の環境が必要で、今は環境がまったくない。
  • ASCII アートでも足りるくらい小さいモデルだが、書き直すたびに線を引き直す手間がかかる。

物理的なイメージと抽象のギャップ

整理するとこうなる。

物理的なイメージ お題の定義 抽象
厚みのある板 盤面=穴ごとの石の数 8つの数の並び
くぼみ 穴(pit)、1〜8、8の隣は1 環状に並んだ容器
小石 石(stone) 区別しないので数だけ
石をつかんで回る手 手(move)=穴を選んで蒔くこと 動作。誰が蒔くかは定義されていない

いちばん大きなギャップは「手」だと思う。お題の「手(move)」は、穴を選んで蒔く動作を指していて、手そのもの(持ち主)ではない。物理的には、手に握った石が残り何個かという状態が蒔いている途中にあるが、抽象では計算途中の一時的な値でしかない。

たたき台を書くとこうなる。まだファイルには書いていない。

classDiagram
    class Board {
        stones of pit 1..8
    }
    class Pit {
        number 1..8
        stones : count
    }
    Board "1" *-- "8" Pit : ring
    note for Board "move(pit) : 選んだ穴の石を時計回りに蒔く"

聞きたいこと

  1. 用語は、お題に合わせて pit にするか。それとも hole か。
  2. 「手で石を握って回る」というイメージは、モデルに残したいか。残すなら「手に持っている石」を明示した概念にする。捨てるなら move は Board の操作の1つになる。
  3. このモデルは docs/model.md に置き、STEP が進むたびに更新していく形でよいか。

User #8 11/13 13:06
IDEで見られるかの確認も含め、ファイルにモデルを書いてください。Gitでバージョン管理しつつ更新していきましょう。用語は、ちゃんと見てなかったので、お題に合わせます。ユビキタス言語、ドメイン辞書ですね。いまの用語の欄で十分そうですが。

📝 コミット 1caa7e4(13:07)

STEP 01時点のドメインモデルを追加

docs/model.md の図(この時点)

classDiagram
    class Board {
        +move(pit)
    }
    class Pit {
        number : 1..8
        stones : int
    }
    Board "1" *-- "8" Pit : 輪の形に並ぶ

🤖 Claude

11/13 13:07

モデルを docs/model.md に書いて、フィーチャーブランチ docs/domain-model にコミットした(1caa7e4)。develop にはまだマージしていない。IDE で表示を確かめてもらってからマージする。

  • 図:Mermaid のクラス図で、Board と8つの Pit を書いた。Board に move(pit) を持たせ、Pit は番号と石の数を持つ。
  • 用語:README の「用語」を正とし、model.md にはその参照だけを書いた。お題に合わせて pit を使っている。
  • 「手」の扱い:前回聞いた点だが、返事がなかったので、石を握った手はモデルに入れず、move を Board の操作にした。この判断は model.md と worklog に書いてある。違うなら直す。
  • worklog:13:07 の項として、お題の見直しとモデル作成の経過を追記した。

IntelliJ の Markdown プレビューで図が表示されるか確認してほしい。Mermaid の表示は IDE の設定で無効になっていることがあり、その場合は図にならずにコードのまま見える。


User #9 11/13 13:08
プレビュー見えました。moveは実装方法は見えてないけど主要な概念なので、move - - > board, move - - >pitと入れておきましょう。多重度も不明。

📝 コミット 4b79e8a(13:09)

ドメインモデルでMoveを独立した概念にする

docs/model.md の図(この時点)

classDiagram
    class Board
    class Pit {
        number : 1..8
        stones : int
    }
    class Move
    Board "1" *-- "8" Pit : 輪の形に並ぶ
    Move ..> Board
    Move ..> Pit

📝 コミット 96d04dc(13:09)

Merge branch 'docs/domain-model' into develop

🤖 Claude

11/13 13:09

Move を独立した概念にしてコミットし(4b79e8a)、develop にマージした(96d04dc)。今は develop にいて、ワークスペースはクリーンだ。

  • 図:Move をクラスとして足し、Move ..> Board と Move ..> Pit の依存を引いた。どちらも多重度は書いていない。
  • Board の move(pit):消した。Move を独立させたのに Board にも操作として残すと、実装方法を決めたように見えるからだ。
  • 説明文:Move は主要な概念なので独立させたこと、実装方法は未定なので依存だけを書いたことを追記した。
  • worklog:プレビューで表示を確認したことと、この変更を追記した。前の行に「move は Board の操作にした」と書いてあるが、時系列の記録なので残してある。

Board の move(pit) を消したのは、やっとむの指示ではなく自分の判断だ。残しておきたいなら戻す。


User #10 11/13 13:09
あまり考えず破線の矢印にしたけど、UMLとしたらどういう意味でしたっけ?

🤖 Claude

11/13 13:09

UML では、破線の開いた矢印(..>)は依存(dependency)を表す。

  • 意味:矢印の元(Move)が先(Board、Pit)を使う。使い方は、引数として受け取る、中で一時的に使う、メソッドを呼ぶ、などがある。
  • 含意:Board や Pit が変わると、Move も影響を受けうる。逆向きの影響はない。
  • 関連との違い:実線の関連(-->)は、相手を属性として持ち続ける構造的なつながりを表す。依存はそれより弱く、「何らかの形で使う」とだけ言う関係だ。

紛らわしいものが1つある。破線でも、先が白抜きの三角(..|>)だと実現(インタフェースの実装)を表し、別の意味になる。

今回の「実装方法はまだ見えないが、Move は Board と Pit を使う」という意図は、依存の意味とずれていない。


User #11 11/13 13:12
よいですね。じゃあこのモデルを頭に入れつつ、テストリストを考えましょう。明らかに初期状態のテスト、Moveのテストがいりますね。01-2の存在しない穴が選べないも必要ですが、実現方法はわからない。暗黙に、穴がループするので8から1にいく場合も明示してテストがいる。テストリストはTODO.mdとして、フラットな箇条書きで書いていきましょう

🤖 Claude

11/13 13:12

ブランチ step-01-test-list を作り、ルートに TODO.md を書いた。まだコミットはしていない。

- 初期盤面は [3,3,3,3,3,3,3,3]
- 初期盤面から穴2を選ぶと [3,0,4,4,4,3,3,3]
- 初期盤面から穴8を選ぶと、8の次の1から蒔いて [4,4,4,3,3,3,3,0]
- 穴0は選べない
- 穴9は選べない
  • 8から1に回るテストは、お題の「穴8を選ぶ」の例がそのまま当てはまるので、その項目に「8の次の1から蒔いて」と明記した。
  • 「存在しない穴」は、0と9でテストが別になるので2項目に分けた。

ファイルには入れていないが、候補として2つ挙げておく。

  • 穴7を選ぶ → [4,3,3,3,3,3,0,4]:8から1へ回るのが、蒔いている途中で起きるケース。穴8の例では最初の1個目で回っている。
  • 穴5を選ぶ → [3,3,3,3,0,4,4,4]:ちょうど穴8で蒔き終わり、回らないケース。境界の確認になる。

聞きたいことが3つある。

  1. この2つを TODO に入れるか。お題の例ではないので、入れるかどうかはやっとむに決めてほしい。
  2. 終わった項目の印はどうするか。- [x] のチェックボックスにするか、取り消し線にするか。
  3. TODO.md は TDD の進行と一緒に何度も変わる。このブランチでコミットだけしておき、実装もこのブランチで続ける形でよいか。

User #12 11/13 13:12
おっとポモドーロがなったので休憩です。一休み増しましょう

🤖 Claude

11/13 13:13

了解、休憩にしよう。

今の状態は次のとおり。

  • ブランチは step-01-test-list。
  • TODO.md は書いただけで、まだコミットしていない。
  • 前回の3つの質問(候補の2項目、完了の印、ブランチの使い方)は、休憩明けに答えてもらえればいい。

User #13 11/13 13:21
候補2つ、良さそうです。そうするとテストリストはフラットにと言いましたが、1つの仕様のいくつかのパターンあるいは複数の同値クラスにたいするテストは、インデントで整理した方が良さそうですね。
チェックボックスにして、未着手は空、完成はxにしましょう。いまやってるのは、Oとかにしましょうか
TODO.mdは常時更新しながら、いまいるブランチに入れていきます。マージするとdevelopに入りますね
実はテストリストにはないけど、言語を選んで環境を作んなきゃならない。これもテストリストの先頭に加えてください。テストリストという名称ですが、私はやることを全部メモしておくTODOリストとして扱うのが好きです

📝 コミット 99eab6a(13:21)

STEP 01のTODOリストを追加

🤖 Claude

11/13 13:21

TODO.md を書き直して、step-01-test-list ブランチにコミットした(99eab6a)。develop にはまだマージしていない。

- [ ] 言語を選んで環境を作る
- [ ] 初期盤面は [3,3,3,3,3,3,3,3]
- [ ] 初期盤面から1手を指す(01-1)
  - [ ] 穴2を選ぶと [3,0,4,4,4,3,3,3]
  - [ ] 穴5を選ぶと、ちょうど穴8で蒔き終わって [3,3,3,3,0,4,4,4]
  - [ ] 穴7を選ぶと、蒔く途中で8から1に回って [4,3,3,3,3,3,0,4]
  - [ ] 穴8を選ぶと、8の次の1から蒔いて [4,4,4,3,3,3,3,0]
- [ ] 存在しない穴は選べない(01-2)
  - [ ] 穴0は選べない
  - [ ] 穴9は選べない
  • 冒頭の説明:TODO.md はやることを全部書くメモであること、印の意味([ ] 未着手、[O] 着手中、[x] 完了)、インデントでまとめるルールを書いた。
  • [O] の表示:Markdown のプレビューでは [ ] と [x] しかチェックボックスにならない。[O] は文字のまま見える。
  • worklog:テストリストを作った経過と、決めたルールを追記した。時刻は記録していなかったので「13:35頃」と推定で書いてある。

User #14 11/13 13:22
まずは初期テストリストはいいかな。これをマージした上で言語環境を作るブランチに入りましょう

📝 コミット 50c9bf7(13:22)

Merge branch 'step-01-test-list' into develop

🤖 Claude

11/13 13:22

step-01-test-list を develop にマージし(50c9bf7)、作業ブランチ setup-env を切った。TODO の「言語を選んで環境を作る」を [O] にしてあるが、まだコミットしていない。

このマシンで使えるのは次のとおり。

  • Python:Python 3.15.2 と uv 0.13.6
  • Node.js:v22.23.4 と pnpm 10.34.7
  • Java、Go、Rust:入っていない

Python + uv + pytest にするつもりだ。理由は次のとおり。

  • 準備が軽い:uv が入っているので、uv init と pytest の追加ですぐ始められる。2時間のセッションでは、環境づくりに時間を取られないことを重視したい。
  • TODO の構造と合う:pytest の parametrize を使うと、TODO でインデントしてまとめた「1つの仕様に対する複数パターン」を、テストでもそのまま1つにまとめて書ける。
  • 他のテスト手法も使える:TDD 以外のテスト戦略も取り入れたいという方針がある。Python には Hypothesis(プロパティベーステスト)があり、たとえば「1手のあとも石の合計は24個のまま」のような性質を検証できる。
  • CLAUDE.md の規約に沿える:exclude-newer で、公開から日の浅いバージョンを避ける設定もすぐできる。

TypeScript + pnpm + Vitest も同じくらい使える。ただ、TypeScript のコンパイル設定やモジュールの設定など、決めることが少し多い。

やっとむが練習したい言語や、使い慣れている言語があれば、そちらを優先する。どうするか。


User #15 11/13 13:24
まあ正直Pythonが慣れてて好きなので、それでいきますか。3.15.2あたりが使えると思います。Python+uv+pytestにします。然るべきリンター、静的チェックも入れましょう。実はあんまりマジメにやってないので、選定はお任せします。選んだものを教えてください。いちおう確認してから承認します

🤖 Claude

11/13 13:24

Python + uv + pytest で進める。リンターと静的チェックは次の組み合わせにするつもりだ。

用途 ツール 選んだ理由
テスト pytest 決定済み
リンター Ruff(ruff check) 速い。flake8、isort、pyupgrade などの機能を1つで担っていて、今の Python では定番
フォーマッタ Ruff(ruff format) Black とほぼ同じ書式になる。リンターと同じツールで済むので、入れるものが増えない
型チェック mypy(strict モード) Python の型チェッカーで最も広く使われている。strict にすると型注釈の書き忘れも指摘される。最初から strict にしておけば、後から厳しくするより楽

型チェッカーの他の候補と、選ばなかった理由は次のとおり。

  • Pyright:速いが、内部で Node.js を使う。
  • Astral の ty(Ruff と同じ作者):今の安定度を自信を持って言えない。

Ruff のルールは、デフォルト(E, F)に次の4つを足すつもりだ。最初から多くは入れず、うるさければ減らす。

  • I:import の並び順
  • B:バグになりやすい書き方
  • UP:古い書き方を新しい Python の書き方に直す
  • SIM:もっと単純に書ける箇所

環境の作り方

  • プロジェクト作成:uv init --lib で作り、src/ レイアウト(src/<パッケージ>/ と tests/)にする。
  • Python のバージョン:requires-python = ">=3.15"
  • 依存のバージョン固定:[tool.uv] に exclude-newer = "2 days" を書き、公開から2日未満のバージョンは入れない。依存はすべて dev 依存として正確なバージョンで固定し、uv.lock をコミットする。実際に入るバージョンは、uv が解決した後に報告する。
  • 実行コマンド:uv run pytest、uv run ruff check、uv run ruff format --check、uv run mypy

確認したいこと

パッケージ名をどうするか。リポジトリ名は tdd-mancara だが、英語の綴りは mancala が一般的だ。パッケージ名は mancala にするつもりでいる。mancara に合わせたいなら、そちらにする。

これでよければ環境を作る。


User #16 11/13 13:25
あらはずかしい。mancalaでお願いします。ツール群の選定、OKです。型ヒントもしっかり書く形でいきます。

🤖 Claude

11/13 13:26

環境はできて、全ツールが動いた。ADR・worklog・README を書いてコミットする。

📝 コミット e75d444(13:26)

Python + uv + pytest の開発環境を作る

Ruff と mypy(strict) を入れ、依存は正確なバージョンで固定する。 言語とツールの選定を ADR 0003 に残す。

開発環境を作って、setup-env ブランチにコミットした(e75d444)。develop にはまだマージしていない。

入れたもの

ツール バージョン 設定
Python 3.15.2 requires-python = ">=3.15"
pytest 9.2.0 testpaths = ["tests"]
Ruff 0.17.4 デフォルトのルールに I, B, UP, SIM を追加
mypy 2.4.1 strict = true。対象は src と tests
  • バージョン固定:uv add は >= で書き込むので、== に書き換えた。exclude-newer = "2 days" を設定し、uv.lock もコミットした。
  • 構成:パッケージは src/mancala/ で、型情報を配布するための py.typed 付き。uv init が作ったサンプル関数 hello() は消して、__init__.py を空にした。

動作確認

  • ruff check、ruff format --check、mypy:問題なし。
  • pytest:テストが0件なので「no tests ran」で終わり、終了コードは5になる。今は想定どおりの結果だ。
  • tests/ ディレクトリは作ったが、ファイルがないので Git には入っていない。最初のテストを書いたときに入る。

記録

  • ADR 0003:言語と開発ツールの決定を書いた。
  • worklog:環境づくりの経過を追記した。
  • README:ADR 0003 への参照と、開発コマンドの一覧を足した。
  • TODO.md:「言語を選んで環境を作る」を [x] にした。

気づいたこと

uv init が Git の設定からやっとむの名前とメールアドレスを読み取り、pyproject.toml の authors に書き込んでいる。そのままコミットに入れた。ローカルのリポジトリだけなので外には出ないが、気になるなら消す。

develop にマージしてよいか。


User #17 11/13 13:28
> 言語は Python 3.15 とする。型ヒントをしっかり書く。
これ1行に書くことではないですね。分けて

pytestの理由に余計なことが書いてありますね。議論してないし、無理に書かないように。

📝 コミット 8e4f725(13:29)

ADR 0003の決定を分け、議論していない理由を消す

🤖 Claude

11/13 13:29

ADR 0003 を2点直して、setup-env にコミットした(8e4f725)。

  • 決定の分割:「言語は Python 3.15 とする」と「型ヒントをしっかり書く」を別々の行にした。
  • 理由の削除:議論していない pytest の理由を2行消した。parametrize の話と Hypothesis の話だ。

今後の ADR では、合意していない理由を足さないこと、決定は1行に1つにすることを、自分用のメモ(メモリ)に残した。

develop へのマージは、まだ返事をもらっていないので保留している。


User #18 11/13 13:30
環境構築してサンプルの落ちるプロダクトコードとテスト (answerは42というやつ) のテストを書いて確認してから、コミットしましょうか

🤖 Claude

11/13 13:30

サンプルのテストを書いて、意図どおり失敗することを確認した。まだコミットしていない。

  • src/mancala/sample.py:answer() -> int が 0 を返す。
  • tests/test_sample.py:assert answer() == 42

実行結果は次のとおり。

  • pytest:assert 0 == 42 で失敗した(終了コード1)。テストの収集、src/ レイアウトからの import、失敗したときの表示まで動いている。
  • ruff check、ruff format --check:問題なし。
  • mypy(strict):3ファイルで問題なし。テストのコードも型チェックの対象に入っている。

前提を1つ確認しておく。環境そのものは前のコミット(e75d444)ですでにコミットしてある。今回コミットするのは、このサンプルの2ファイルになる。

コミットの仕方は2通りある。

  • 失敗するテストのままコミットする:Red の状態を履歴に残す。
  • answer() を 42 に直して通してからコミットする:Green にしてからまとめて残す。

Canon TDD の練習として Red も履歴に残すなら、前者でコミットしてから直してもう一度コミットする形になる。どちらにするか。


User #19 11/13 13:32
いい質問です。レッドでコミット、グリーンでコミット、リファクタリングでコミットとしましょう。それぞれ最低1回で、なにか間違えたり追加変更したら複数コミットがあって良いです。和田さんの言ってた、なんだっけ、コミットコメントにtest:とかrefactor:とかfeature:とかfix:とか書くあれをやりましょう

📝 コミット 183944f(13:32)

test: 環境確認用にanswer()が42を返すテストを追加

--- /dev/null
+++ b/src/mancala/sample.py
@@ -0,0 +1,2 @@
+def answer() -> int:
+    return 0
--- /dev/null
+++ b/tests/test_sample.py
@@ -0,0 +1,5 @@
+from mancala.sample import answer
+
+
+def test_answer() -> None:
+    assert answer() == 42

📝 コミット c5a4d7e(13:32)

feat: 環境確認用のanswer()が42を返す

--- a/src/mancala/sample.py
+++ b/src/mancala/sample.py
@@ -1,2 +1,2 @@
 def answer() -> int:
-    return 0
+    return 42

🤖 Claude

11/13 13:33

Now ADR 0004 for the commit rule.

📝 コミット 9074afa(13:33)

docs: TDDのステップごとのコミットの決まりをADR 0004に残す

サンプルを Red と Green でコミットし、コミットの決まりを ADR 0004 に残した。全部 setup-env ブランチにある。

9074afa docs: TDDのステップごとのコミットの決まりをADR 0004に残す
c5a4d7e feat: 環境確認用のanswer()が42を返す
183944f test: 環境確認用にanswer()が42を返すテストを追加

Green にしたあと、pytest、ruff、mypy はすべて通った。

ADR 0004 の「背景と理由」には、最初は自分で考えた理由を書いていた。前の指摘と同じ間違いなので、やっとむが言ったこと(t-wada さんが話していたプレフィックスのやり方を取り入れる)だけにして、コミットを修正(amend)した。

あの付け方は Conventional Commits という形式だ。ただ、t-wada さんが実際にこれを使っていたかどうかは確認できていない。前に読んだのは記事の最初の1/4だけで、その範囲にはなかった。

決めてもらいたいことが3つある。

  1. プレフィックスの種類:やっとむが挙げたのは test: refactor: feature: fix: だった。ADR では次のようにしている。違うなら直す。
    • feature: は Conventional Commits の書き方に合わせて feat: にした。
    • docs:(ドキュメント)と chore:(環境や設定)を足した。今のコミットにはこの2種類も必要になるからだ。
  2. サンプルの Refactor:「各ステップで最低1回コミットする」と決めたが、answer() には直すところがない。Refactor のコミットを省くか、何か作るか。
  3. develop へのマージ:環境構築とサンプルが揃ったので、setup-env を develop にマージしてよいか。

User #20 11/13 13:34
1->OKです
2->リファクタリングで変更なければ、コミットなしでOK
3->LGTM

📝 コミット 096afa3(13:34)

docs: Refactorで変更がなければコミットしないことをADR 0004に追記

📝 コミット 80b6e25(13:34)

Merge branch 'setup-env' into develop

🤖 Claude

11/13 13:34

3つとも反映して、setup-env を develop にマージした(80b6e25)。今は develop にいて、ワークスペースはクリーンだ。

  • プレフィックス:ADR 0004 の内容(feat: を使い、docs: と chore: を足す形)で確定した。worklog にも、こうした経緯を追記した。
  • Refactor:ADR 0004 に「Refactor で変更がなければコミットしない」と追記して、docs: でコミットした(096afa3)。

User #21 11/13 13:38
さて、では最初の機能にいきますか。初期状態のテストだから expected == [3,3,3,3,3,3,3,3,] というアサートになると思うんだけど、これはあくまでインターフェースであって内部表現がlistということではない。じつは内部表現についてはアイデアもあって、石の個数をlistで持つというのはたぶん普通、いっぽう石がどこにあるかというデータの持ち方もあると思う。石にアイデンティティがあると思えばdictで居場所(どの穴か)を持てるし、そうでなければ穴の番号やidを持つbagで表現できる。というわけで内部表現とインターフェースを分離することを意識しつつ、いまの時点ではまあsutがいきなりlistを持つという形がいちばんシンプルでしょう。

🤖 Claude

11/13 13:38

内部表現とインターフェースを分けて考える、という方針は了解した。今の時点では、SUT(テスト対象)が石の数を list で持つ、いちばん単純な形で始める。

テストを書く前に、インターフェースの案を見てほしい。

from mancala.board import Board


def test_初期盤面はすべての穴に石が3個() -> None:
    board = Board()
    assert board.stones() == [3, 3, 3, 3, 3, 3, 3, 3]

この形にした理由は次のとおり。

  • Board() で初期盤面にする:今のお題には初期盤面しか出てこない。Board.initial() のようなファクトリは、初期盤面以外が必要になってから考えればいい。
  • stones() はメソッドにする:お題の用語では、盤面は「穴1〜8それぞれの石の数」だ。属性として見せると、内部に list をそのまま持っているように見える。メソッドにしておけば、「求めると list で返ってくる」というインターフェースに見えるので、内部表現と分けておきやすい。
  • テスト名は日本語にする:TODO.md の文言と対応させやすい。Python は識別子に日本語を使え、Ruff と mypy も問題にしない。

聞きたいことが3つある。

  1. この形でよいか。特に、名前が stones() でよいか。
  2. 内部表現のアイデア(石の数の list、石ごとの居場所を持つ dict、穴番号の bag)は、今は採用しないが、残しておく価値がある。worklog に書いておくつもりだが、よいか。
  3. 環境確認用の answer() のサンプルは、役目を終えたので、このタイミングで消してよいか。

よければ、ブランチ step-01-initial-board を切り、TODO を [O] にして、Red のテストから始める。


User #22 11/13 13:40
それでいきましょう。listの最後のカンマについて、一般的ルールはある? なんとなくつけておく派です

📝 コミット b32ef03(13:40)

chore: 環境確認用のサンプルを削除

--- a/src/mancala/sample.py
+++ /dev/null
@@ -1,2 +0,0 @@
-def answer() -> int:
-    return 42
--- a/tests/test_sample.py
+++ /dev/null
@@ -1,5 +0,0 @@
-from mancala.sample import answer
-
-
-def test_answer() -> None:
-    assert answer() == 42

📝 コミット c2be949(13:40)

test: 初期盤面はすべての穴に石が3個

--- /dev/null
+++ b/tests/test_board.py
@@ -0,0 +1,6 @@
+from mancala.board import Board
+
+
+def test_初期盤面はすべての穴に石が3個() -> None:
+    board = Board()
+    assert board.stones() == [3, 3, 3, 3, 3, 3, 3, 3]

🤖 Claude

11/13 13:40

まず質問に答える。末尾のカンマについての一般的なルールは次のとおり。

  • PEP 8:末尾のカンマは基本的に任意で、必須なのは要素が1つのタプル (x,) だけ。勧められているのは、要素を1行に1つずつ並べ、閉じかっこを次の行に置くときだ。こうすると、要素を足したときの差分が1行で済む。[3, 3, 3,] のように閉じかっこと同じ行に付けるのは、勧められていない。
  • Ruff format(Black と同じ):「マジックトレーリングカンマ」という挙動がある。末尾にカンマがあると、1行に収まる長さでも、要素を1行に1つずつ展開する。
    • [3, 3, 3, 3, 3, 3, 3, 3,] と書くと、フォーマット後は8行に展開される。
    • カンマがなく1行に収まるなら、1行のまま残る。

盤面のリテラルは1行のほうが読みやすいので、テストでは末尾のカンマを付けていない。

「それでいきましょう」を、前回の3つの質問すべてへの承認と受け取って、ここまで進めた。全部 step-01-initial-board ブランチにある。

c2be949 test: 初期盤面はすべての穴に石が3個
b32ef03 chore: 環境確認用のサンプルを削除
  • b32ef03:サンプルの answer() とそのテストを消した。
  • c2be949(Red):tests/test_board.py に、案のとおりのテストを書いた。TODO の「初期盤面は…」を [O] にし、worklog に内部表現のアイデアとインターフェースの方針を書いて、同じコミットに入れた。
  • 失敗の確認:mancala.board がまだないので、ModuleNotFoundError で失敗する。Canon TDD の Red としてはこれでよいと考えている。モジュールだけ先に作って、値が違うことで失敗させる段階を踏みたいなら、そうする。

次は Green で、src/mancala/board.py に Board を作る。進めてよいか。


User #23 11/13 13:41
ここで5分間休憩です。☕

🤖 Claude

11/13 13:41

了解、休憩にしよう。☕

今は step-01-initial-board ブランチで、Red のテストをコミットしたところ(c2be949)だ。ワークスペースはクリーンで、残っている作業はない。休憩が終わったら Green から再開する。


User #24 11/13 13:43
雑談だが、stonesはロックバンドを想起させますね。

🤖 Claude

11/13 13:44

たしかに、ローリング・ストーンズだ。board.stones() と書くと、石の数ではなくメンバー一覧が返ってきそうな気もする。

ちなみに「転がる石に苔むさず」(A rolling stone gathers no moss)は、マンカラにもある意味で当てはまる。石は蒔かれて穴から穴へ移り続け、1つの穴にとどまらない。


User #25 11/13 13:44
うまいこといいますね

🤖 Claude

11/13 13:44

ありがとう。休憩が明けたら、Green から始めよう。


User #26 11/13 13:44
超マニア的な話題としては、StonesはUltima世界 (Britannia) 有名な吟遊詩人Ioloの名作でもあります

🤖 Claude

11/13 13:45

それはマニアックだ。Iolo の「Stones」は、Ultima シリーズで繰り返し使われる曲だった。Iolo には現実のモデルがいて、作者 Richard Garriott の友人の David Watson だったはずだ。

記憶違いがあるかもしれないが、Ultima V では、城のハープシコードでこの曲の音を弾くと隠し通路が開く仕掛けもあった。

マンカラの石も、正しい順番で穴に蒔くと何かが開くのかもしれない。STEP が進めばわかる。


User #27 11/13 13:46
さて、再開しますか。いまレッド、最短でグリーンにします。

📝 コミット b2a8fa7(13:46)

feat: 初期盤面はすべての穴に石が3個

--- /dev/null
+++ b/src/mancala/board.py
@@ -0,0 +1,3 @@
+class Board:
+    def stones(self) -> list[int]:
+        return [3, 3, 3, 3, 3, 3, 3, 3]

🤖 Claude

11/13 13:46

Green にして、コミットした(b2a8fa7)。

class Board:
    def stones(self) -> list[int]:
        return [3, 3, 3, 3, 3, 3, 3, 3]

最短で通すために、固定値をそのまま返す「仮実装」(Fake It)にした。内部にはまだ何も持たせていない。pytest、ruff、mypy はすべて通った。

TODO の「初期盤面は…」は、Refactor が終わるまで [O] のままにしておく。

次は Refactor だ。今のコードに、直すべき重複や読みにくさは見当たらない。固定値を list の属性に移すのは、実装を一般化することになる。その動機になるテスト(1手を指して盤面が変わる)がまだないので、今やると先回りになると考えている。このまま Refactor はなしにして、TODO を [x] にしてよいか。


User #28 11/13 13:47
基本的に同意です。stones()をget_stoines()とかread_stones()とかに、するかどうかというのは考えてもいい。Pythonの基本的な命名規約には特に指定がないと思うし、自分としてはstones()が最適な感じです。もうひとつは、list[int]をに型名を付けるかどうか。

🤖 Claude

11/13 13:48

命名について。PEP 8 には、アクセサに get_ を付けるかどうかの決まりはない。Python では、単純に値を返すだけのものには get_ を付けず、名詞のまま(stones() や属性)にする書き方が一般的だ。read_ は、ファイルや I/O から読む印象が強い。自分も stones() がいちばん合っていると思う。

型名(型エイリアス)について。Python 3.12 以降は type Stones = list[int] と書ける。付ける場合と付けない場合の違いはこうなる。

  • 付ける利点:「石の数の並び」というドメインの概念に名前が付き、シグネチャを読むだけで意味がわかる。
  • 付けても変わらないこと:エイリアスは list[int] と同じ型として扱われる。ただの list[int] を渡しても、mypy は区別しない。型の安全性は上がらず、名前が付くだけだ。
  • 今の使用箇所:1か所だけ。

今は付けないつもりだ。1か所なら、名前を付けても読みやすさはあまり変わらない。1手を指すテストに進めば、Move の結果としても同じ形が出てくるので、そこで付けるか決めればいい。

それとは別に、名前を付けるなら考えておきたいことがある。お題の用語では「盤面(board):穴1〜8それぞれに入っている石の数」となっている。つまり、お題が言う盤面はこの list そのものだ。一方、コードでは Board クラスが盤面で、list は stones() の戻り値になっている。

型名を付けるなら、用語とコードのこの対応をどう取るかも一緒に決めることになる。Stones とするか、お題に合わせて board 系の名前にするか、だ。

この考えでよければ、Refactor はなしで TODO を [x] にする。


User #29 11/13 13:49
同意します。ただし型名をStonesにするのは、あなたのその理由により微妙だと思われる。どちらかといえばPitsですね

📝 コミット 3bcf070(13:49)

docs: 初期盤面のTODOを完了にし、型名の検討をworklogに残す

🤖 Claude

11/13 13:49

Refactor はなしにして、TODO の「初期盤面は…」を [x] にし、コミットした(3bcf070)。

型名の候補は Pits にすることも worklog に残した。list の要素1つが穴1つの石の数なので、並び全体を「穴の並び」と読むのは自然だと思う。実際に付けるかは、Move の結果で同じ形が出てきたときに決める。

初期盤面の作業はこれで区切りがついた。step-01-initial-board を develop にマージしてから、1手を指す(01-1)のブランチに移ってよいか。


User #30 11/13 13:50
OK

📝 コミット fa0952f(13:50)

Merge branch 'step-01-initial-board' into develop

🤖 Claude

11/13 13:50

step-01-initial-board を develop にマージした(fa0952f)。新しいブランチ step-01-move を切り、TODO の「初期盤面から1手を指す」と「穴2を選ぶと…」を [O] にした。TODO の変更はまだコミットしていない。Red のテストと一緒にコミットする。

テストを書く前に、1手を指すインターフェースを決めたい。候補は3つある。

A. 盤面を書き換える

board = Board()
board.move(2)
assert board.stones() == [3, 0, 4, 4, 4, 3, 3, 3]

B. 新しい盤面を返す(元の盤面は変えない)

board = Board().move(2)
assert board.stones() == [3, 0, 4, 4, 4, 3, 3, 3]

C. Move を独立したものにする

board = Move(2).apply(Board())
assert board.stones() == [3, 0, 4, 4, 4, 3, 3, 3]

B にするつもりだ。理由は次のとおり。

  • お題は「1手を指したあとの盤面を求めます」と書いている。入力から結果を求める形なので、新しい盤面を返すほうが素直に表せる。
  • 元の盤面が変わらないので、テストの中で状態の変化を追わなくていい。
  • C はモデルの図にある Move をそのままクラスにした形だ。ただ、今の仕様で Move が持つのは「どの穴を選ぶか」だけで、クラスにする理由がまだない。Move をメソッド名に残しておけば、Move を独立させる必要が出たときにも移しやすい。

また、TODO で同じグループにまとめた4パターン(穴2、5、7、8)は、最初から parametrize にはしないつもりだ。まず穴2の1件だけで書き、2件目を足すときに、まとめるかどうかを Refactor で判断する。

B でよいか。


User #31 11/13 13:54
いいですね。テストコードをサンプルコードと考え、さらにクライアントにとって使いやすいかどうか判断する場と考えましょう。案BはBoardはimuutableという設計をクライアントに対して露出するものになっている。はてさて、環マンカラという謎のゲームのメンタルモデルとしては、手を打つたびにあらたな盤面が現れるんでしょうかね? 盤面の上で石が動いていくんですかね? どちらもアリなんだけど、いまのお題の書きぶりだと「初期盤面から1手を指したあとの盤面を求めます。」なので、前者にするのが素直っぽいですね。案Cは内部実装で現れるかもしれないなと思います。
とりあえずこの意見への回答をください

🤖 Claude

11/13 13:54

3点とも同意する。

テストをサンプルコードとして読む
B の board = Board().move(2) は、「move は盤面を返す」と読める。ただ、「元の盤面は変わらない」ことまで読み取れるかというと、弱い。immutable であることをクライアントに約束する設計にするなら、それ自体がお題で決まっていない決定になる。お題は、そうした決定を「テストとして残します」と言っている。だとすると、「move しても元の盤面は変わらない」というテストがあってもいい。

メンタルモデル
物理的なマンカラなら、盤面は1つで、その上を石が動いていく。モデルを作ったときに話した「石を握って回る手」と同じギャップだと思う。物理的なイメージでは状態が変わっていき、お題の抽象では盤面から盤面への変換になる。今のお題の書き方は「初期盤面から…あとの盤面を求めます」だから、新しい盤面が現れる、つまり後者の抽象のほうが素直だ。今後の STEP で手を続けて指すような仕様が出てきたら、そのときに見直せばいい。

案 C
同意する。モデルの図で Move は Board と Pit に依存する概念として書いてあり、内部実装で「1手を表すもの」として現れることは十分ありえる。それをクライアントに見せるかどうかは別の話で、今は move() をメソッドにしておけば足りる。

1つ聞きたい。immutable を約束として明示するテスト(元の盤面が変わらない)を、TODO に足すか。


User #32 11/13 13:56
ありがとう。いずれも同意します。immutableのテストも足しましょう

📝 コミット 9243f6b(13:56)

test: 初期盤面から穴2を選ぶと穴3から5に1個ずつ蒔かれる

--- a/tests/test_board.py
+++ b/tests/test_board.py
@@ -4,3 +4,8 @@ from mancala.board import Board
 def test_初期盤面はすべての穴に石が3個() -> None:
     board = Board()
     assert board.stones() == [3, 3, 3, 3, 3, 3, 3, 3]
+
+
+def test_初期盤面から穴2を選ぶと穴3から5に1個ずつ蒔かれる() -> None:
+    board = Board().move(2)
+    assert board.stones() == [3, 0, 4, 4, 4, 3, 3, 3]

🤖 Claude

11/13 13:56

TODO に immutable の項目を足し、穴2のテストを Red でコミットした(9243f6b)。

TODO には、01-1 のグループの直後に1行足した。

- [ ] 1手を指しても元の盤面は変わらない(お題にはなく、自分で決めた仕様)

01-1 の子にしなかったのは、あのグループが「穴ごとのパターン」の集まりだからだ。こちらは設計上の決定なので、別の項目にした。

テストは次のとおり。

def test_初期盤面から穴2を選ぶと穴3から5に1個ずつ蒔かれる() -> None:
    board = Board().move(2)
    assert board.stones() == [3, 0, 4, 4, 4, 3, 3, 3]
  • 失敗の確認:AttributeError: 'Board' object has no attribute 'move' で失敗する。既存の初期盤面のテストは通ったままだ。
  • worklog:インターフェースの3案、メンタルモデルの議論、immutable のテストを足した理由を追記した。

次は Green だ。最短で通すなら、move() が固定値の盤面を返す仮実装になる。ただ、Board は今、内部に何も持っていない。固定値の [3, 0, 4, 4, 4, 3, 3, 3] を持つ Board を返すには、Board が石の数を受け取れるようにする必要がある。

ここが、Canon TDD の「仮実装」から「三角測量」か「明白な実装」へ移る判断の場面だと思う。どちらにするか、やっとむの考えを聞きたい。


User #33 11/13 13:59
Boardが(初期状態の)listを持っているのはよい、move()がいきなり3つの石を3箇所に撒くのは、なんかちょっとステップが大きすぎる気がするなあ。いや、別にそんなことないか。そこじゃない、内部表現がまだ決まってないところかな。つまり内部表現によって「明白な実装」のロジックは大きく変わりますね。まずは三角測量じゃないかと思いますが、どうです?

🤖 Claude

11/13 13:59

三角測量に賛成する。

  • 内部表現が先に決まってしまう:やっとむの言うとおり、「明白な実装」で書くには、そのときに内部表現を決める必要がある。石の数の list なら、添字を回しながら1つずつ足すロジックになる。石の居場所を持つ bag なら、石の居場所を書き換えるロジックになる。例が穴2の1件しかない段階で決めると、その1件に合わせた形になりやすい。
  • 2件目が一般化の理由になる:三角測量なら、穴2は仮実装で通しておき、2件目の例を足して仮実装では通らなくなったところで一般化する。その時点では2つの例を見比べながら、内部表現を選べる。
  • ステップの大きさ:3箇所に蒔くこと自体は大きくないと思う。ただ、選んだ穴を空にすることと、隣から順に蒔くことの2つが一度に入る。2件目で、どちらが本質的かも見えやすくなる。

2件目は、TODO の順だと穴5(ちょうど穴8で蒔き終わる)だ。8から1に回る話はまだ入らないので、一般化の最初の一歩としてもちょうどいい大きさだと思う。

ただ、仮実装でも決めなければならないことが1つある。move() が固定値の盤面を返すには、Board を任意の石の数で作れる必要がある。作り方は2通りある。

  • コンストラクタの引数にする(Board(stones)):いちばん単純だ。ただ、任意の盤面を作れることがクライアントへの公開インターフェースになる。今のお題には、初期盤面以外から始める仕様はない。
  • 内部用のクラスメソッドにする(Board._of(stones) など):クライアントに見えるのは Board()、move()、stones() だけのままで済む。

後者にするつもりだ。テストをクライアントの使い方の見本と考えるなら、お題が求めていない「任意の盤面を作る」機能は見せないほうがいい。どうか。


User #34 11/13 14:03
別の提案をしていいですか。Boardに公開インターフェースとして、ある穴から別の穴に石を1つ移動するというメソッドを加える。。move()の実装は、そのメソッドを使う。くわえて、Boardのコピーコンストラクタみたいのを作る(Pythonだとどうするんだっけ?) これで、内部表現を決めるのを送らせられます。つまり新しいメソッドの内部をいったん仮実装というか、動作するけど理想じゃない形にしておきましょう。move()はどの穴から石をどう移動するというルールを表現することになります。うん、これはTODOリストの更新が必要そうですね

🤖 Claude

11/13 14:03

提案はいいと思う。move() が「どの穴からどの穴へ石を移すか」というルールだけを表し、「石を1つ移す」操作が内部表現を隠すことになる。内部表現に触れるのは、その操作と stones() だけになる。

コピーコンストラクタ
Python には C++ のようなコピーコンストラクタはない。よく使う方法は3つある。

  • copy() メソッドを作る:list.copy() や dict.copy() と同じ書き方で、Python ではいちばん素直だ。
  • 標準ライブラリの copy.copy(board) か copy.deepcopy(board) を使う:何も実装しなくても動く。
  • コンストラクタで Board を受け取る(Board(other)):あまり見かけない。

immutable との関係(ここだけ確認したい)
石を1つ移すメソッドを公開すると、それが盤面を書き換えるメソッドになる場合、さっき決めた「Board は immutable」と矛盾する。クライアントが直接呼べば、盤面が変わってしまうからだ。取りうる形は2つある。

  • 石を移すメソッドも新しい盤面を返す:board.move_stone(2, 3) が新しい Board を返す。move() は、それを石の数だけ繰り返して結果をつなげていく。immutable のままなので、コピーは要らなくなる。
  • 石を移すメソッドは盤面を書き換えるが、非公開にする:move() の中でコピーを作り、そのコピーを書き換える。クライアントから見える Board は immutable のまま保てる。ただし、石を移すメソッドは公開インターフェースではなくなる。

公開にしたいという意図を尊重するなら、前者にするつもりだ。コピーを作る仕組みも不要になり、作るものが1つ減る。

名前
お題の用語には「石を1つ移す」がない。新しい用語になるので、名前を決めたい。move は「手」としてもう使っているので、move_stone(from_pit, to_pit) を考えている。

今ある Red のテスト
穴2のテストは失敗したままコミットされている。石を1つ移すメソッドを先にテスト駆動で作るなら、その間は穴2のテストを @pytest.mark.skip で一時的に止めておくつもりだ。Canon TDD では、一度に扱う失敗テストは1つにするからだ。

TODO は、この3点が決まったら更新する。どうか。


User #35 11/13 14:06
copy()メソッドの新設で行きましょう
1つ移すメソッドもimmutableとするのが、筋ですね。パフォーマンスが気になるならあとで最適化するけど、ぜったい気にならない
ただ、公開するのに強い意志はないです。ただ、あとで役に立ちそうな気がするというところ。アンダーバーつけても特に変わらないです
move_a_stone()がいいかな
テストはいったんskipにして、テストリストの別項目に移動しましょう

📝 コミット 0c35af7(14:06)

test: 穴2のテストを一時的にskipし、move_a_stone()を先に作る

--- a/tests/test_board.py
+++ b/tests/test_board.py
@@ -1,3 +1,5 @@
+import pytest
+
 from mancala.board import Board
 
 
@@ -6,6 +8,7 @@ def test_初期盤面はすべての穴に石が3個() -> None:
     assert board.stones() == [3, 3, 3, 3, 3, 3, 3, 3]
 
 
+@pytest.mark.skip(reason="先に move_a_stone() を作る")
 def test_初期盤面から穴2を選ぶと穴3から5に1個ずつ蒔かれる() -> None:
     board = Board().move(2)
     assert board.stones() == [3, 0, 4, 4, 4, 3, 3, 3]

📝 コミット 10bde42(14:06)

test: 初期盤面で穴2から穴3に石を1つ移す

--- a/tests/test_board.py
+++ b/tests/test_board.py
@@ -12,3 +12,8 @@ def test_初期盤面はすべての穴に石が3個() -> None:
 def test_初期盤面から穴2を選ぶと穴3から5に1個ずつ蒔かれる() -> None:
     board = Board().move(2)
     assert board.stones() == [3, 0, 4, 4, 4, 3, 3, 3]
+
+
+def test_初期盤面で穴2から穴3に石を1つ移す() -> None:
+    board = Board().move_a_stone(2, 3)
+    assert board.stones() == [3, 2, 4, 3, 3, 3, 3, 3]

🤖 Claude

11/13 14:06

決めたとおりに TODO とテストを変えて、move_a_stone() の Red まで進めた。

10bde42 test: 初期盤面で穴2から穴3に石を1つ移す
0c35af7 test: 穴2のテストを一時的にskipし、move_a_stone()を先に作る

TODO の変更(着手中は move_a_stone() に移した)

- [O] 石を1つ移す move_a_stone()(新しい盤面を返す)
  - [O] 初期盤面で穴2から穴3に1つ移すと [3,2,4,3,3,3,3,3]
- [ ] Board の copy() を作る
- [ ] 初期盤面から1手を指す(01-1)
  - [ ] 穴2を選ぶと [3,0,4,4,4,3,3,3](テストは skip 中)
  ...
- [ ] 1手を指しても、石を1つ移しても、元の盤面は変わらない(…)
  • immutable の項目:move_a_stone() も新しい盤面を返すことにしたので、こちらにも当てはまるように書き換えた。
  • 穴2のテスト:@pytest.mark.skip(reason="先に move_a_stone() を作る") を付けて止めた。

Red のテスト

def test_初期盤面で穴2から穴3に石を1つ移す() -> None:
    board = Board().move_a_stone(2, 3)
    assert board.stones() == [3, 2, 4, 3, 3, 3, 3, 3]

AttributeError: 'Board' object has no attribute 'move_a_stone' で失敗する。初期盤面のテストは通ったままで、穴2のテストは skip されている。

worklog には、三角測量を考えた理由と、やっとむの提案と、そこで決めたことを書いた。

確認したいことが2つある。

  1. copy() のテスト:TODO に copy() の項目を入れたが、copy() だけを直接テストするかは決めていない。今は、move_a_stone() を Green にするときに中で使い、間接的にテストされる形になると考えている。直接のテストも書くか。
  2. Green の進め方:move_a_stone() の Green も、仮実装(固定値を返す)から始めるか。ここで内部の list を持たせる明白な実装にするか。move_a_stone() は、やっとむが「動作するけど理想じゃない形」でよいと言っていた場所だ。石の数の list を持ち、2つの要素を増減するだけの実装なら、明白な実装で十分だと思う。

User #36 11/13 14:08
1->いまは不要でOK
2->listを使う明白な実装で行きましょう

ところでimmutableの件ですが、オブジェクトとして真にimmutableであることと、公開APIについてはimmutableのように振る舞うというので、違う設計が可能と言えば可能ですねえ。ちょっとこのことについてメリデメを整理して論じてもらえますか

📝 コミット 3c505ac(14:09)

feat: 石を1つ移すmove_a_stone()をlistで実装

--- a/src/mancala/board.py
+++ b/src/mancala/board.py
@@ -1,3 +1,17 @@
 class Board:
+    def __init__(self) -> None:
+        self._stones = [3, 3, 3, 3, 3, 3, 3, 3]
+
     def stones(self) -> list[int]:
-        return [3, 3, 3, 3, 3, 3, 3, 3]
+        return self._stones.copy()
+
+    def copy(self) -> Board:
+        new = Board()
+        new._stones = self._stones.copy()
+        return new
+
+    def move_a_stone(self, from_pit: int, to_pit: int) -> Board:
+        new = self.copy()
+        new._stones[from_pit - 1] -= 1
+        new._stones[to_pit - 1] += 1
+        return new

🤖 Claude

11/13 14:09

Green の実装をコミットした(3c505ac)が、1つ問題がある。

class Board:
    def __init__(self) -> None:
        self._stones = [3, 3, 3, 3, 3, 3, 3, 3]

    def stones(self) -> list[int]:
        return self._stones.copy()

    def copy(self) -> Board:
        new = Board()
        new._stones = self._stones.copy()
        return new

    def move_a_stone(self, from_pit: int, to_pit: int) -> Board:
        new = self.copy()
        new._stones[from_pit - 1] -= 1
        new._stones[to_pit - 1] += 1
        return new

stones() は、内部の list ではなくコピーを返すようにした。内部の list をそのまま返すと、クライアントがそれを書き換えたときに盤面が変わってしまう。

問題:mypy が通っていないままコミットした
pytest は「2 passed, 1 skipped」で通った。しかし mypy が、skip 中の穴2のテストについて "Board" has no attribute "move" を報告している。skip はテストの実行を止めるだけで、型チェックは止めないからだ。

自分のコマンドの組み方に誤りがあり、mypy が失敗してもコミットまで進んでしまった。チェックがすべて通ったのを確かめてからコミットする、という手順になっていなかった。

直し方は2つある。

  • skip 中のテストの該当行に # type: ignore[attr-defined] を付ける。skip を外すときに一緒に消す。
  • move() を作るまで、mypy のエラーを受け入れる。

前者にするつもりだ。チェックが通らない状態が続くと、新しいエラーが出ても気づきにくくなるからだ。修正は fix: でコミットする。


真に immutable と、公開 API で immutable に振る舞う設計

A. オブジェクトとして真に immutable

内部状態を一度作ったら変えない。たとえば @dataclass(frozen=True) にして、中身を tuple で持つ。

メリット
- 構造そのものが保証になる。将来メソッドを足しても、うっかり状態を書き換えることが起きにくい。
- ハッシュ可能にできる。盤面を dict のキーや set の要素に使える。同じ盤面の判定、探索、メモ化に役立つ。
- 等価性(==)を値で定義するのが自然になる。

デメリット
- 新しい状態を作るたびに、状態全体を渡してオブジェクトを作る必要がある。つまり、任意の石の数を受け取る手段が要る。さっき避けた「任意の盤面を作れることを公開する」問題がまた出てくる。内部用の生成手段で隠すことはできる。
- 蒔くような処理は、1つずつ状態を変えながら書くのが自然だ。immutable だと、毎回新しい tuple を作るか、結果をまとめて計算する書き方になる。
- 内部表現の選択肢が狭まる。bag なら collections.Counter が自然だが、これは変更可能なオブジェクトだ。immutable にするには frozenset や tuple などで工夫が要る。
- Python では、真の immutable といっても慣習レベルだ。object.__setattr__ を使えば書き換えられる。

B. 内部は変更可能で、公開 API では immutable に振る舞う

今の実装がこちらだ。公開メソッドはコピーを作ってから書き換え、外には内部の list を渡さない。

メリット
- 実装の自由度が高い。コピーした盤面を内部で書き換えながら蒔く、という素直なループが書ける。
- 内部表現を選ぶときの制約が少ない。
- コンストラクタを引数なしのまま保てる。

デメリット
- 保証が規律頼みになる。すべての公開メソッドで「書き換える前にコピーする」「内部の list を外に返さない」を守る必要がある。今回 stones() でコピーを返したのも、その規律の1つだ。メソッドを足したときに破っても、構造では防げない。
- ハッシュ可能にするのは危険だ。内部が変わりうるオブジェクトにハッシュを定義すると、dict や set に入れたあとで値が変わる可能性が残る。

今の状況での位置づけ

TODO にある「元の盤面は変わらない」のテストは、公開 API の振る舞いだけを確かめる。A でも B でも通る。

つまり、どちらを選ぶかは内部設計の問題で、このテストがあれば後からリファクタリングで切り替えられる。切り替える理由になりそうなのは、盤面の同一判定やハッシュが必要になったとき(A に寄せる)だ。あるいは、蒔く処理を内部の書き換えで書きたくなったとき(B のまま)だ。


mypy の件は、# type: ignore[attr-defined] で直してよいか。


User #37 11/13 14:14
mypyの件は、エラー無視でいいんじゃないかな
immutableについては、言語機能とは別レベルの設計判断になります。それで、変更もできる一方でB->Aは容易だけどA->Bは影響が大きそうと言うのはあります。move_a_stone()がimmutableとして振る舞うというのはOKで、設計判断としては外部からはimmutableに見えたり、そのように振る舞うということにしておきましょう。これはADRにしたほうがよいですね
休憩時間ですが、すみませんがこれだけやってからにしてください

📝 コミット 571f644(14:14)

fix: skip中のテストのmove()への型エラーを一時的に無視する

--- a/tests/test_board.py
+++ b/tests/test_board.py
@@ -10,7 +10,7 @@ def test_初期盤面はすべての穴に石が3個() -> None:
 
 @pytest.mark.skip(reason="先に move_a_stone() を作る")
 def test_初期盤面から穴2を選ぶと穴3から5に1個ずつ蒔かれる() -> None:
-    board = Board().move(2)
+    board = Board().move(2)  # type: ignore[attr-defined]
     assert board.stones() == [3, 0, 4, 4, 4, 3, 3, 3]

📝 コミット 32f4ead(14:14)

docs: Boardは外部からimmutableに見えるように振る舞うことをADR 0005に残す

🤖 Claude

11/13 14:15

2つとも済ませた。今回はチェックを1つずつ実行し、すべて通ったのを確かめてからコミットしている。

32f4ead docs: Boardは外部からimmutableに見えるように振る舞うことをADR 0005に残す
571f644 fix: skip中のテストのmove()への型エラーを一時的に無視する
  • mypy:「エラー無視」を # type: ignore[attr-defined] と受け取り、skip 中のテストの1行に付けた。pytest、ruff、mypy はすべて通っている。skip を外すときに一緒に消す。
  • ADR 0005:「決めたこと」「背景と理由」「検討した他の案」は、やっとむが言ったことと、今の議論で出た内容だけで書いた。
  • README:ADR の一覧に 0004 が抜けていたので、0005 と一緒に足した。
  • worklog:mypy の件をコミットした経緯と、immutable の議論を追記した。

TODO の move_a_stone() の項目は、まだ [O] のままだ。Refactor をするかどうかは、休憩のあとに決めよう。ゆっくり休んで。


User #38 11/13 14:17
さて、最後のポモドーロです。早いな、まだSTEP1の初手ですよね。

🤖 Claude

11/13 14:17

そうだ。コードとしては、STEP 01 の最初の手のところにいる。

できたこと
- 初期盤面(Board() と stones())
- 石を1つ移す move_a_stone()(Green まで。Refactor はまだ決めていない)

まだのこと
- 1手を指す move()(01-1):穴2のテストは skip 中で、穴5、7、8 は未着手
- 元の盤面が変わらないことのテスト
- 存在しない穴(01-2):穴0と穴9

ここまでの3ポモドーロでは、コード以外の土台に多くの時間を使った。

  • ブランチ戦略、記録の残し方、言語とツール、コミットの決まりを ADR 0001〜0004 にまとめた。
  • ドメインモデルと TODO リストを作った。
  • 環境を作り、サンプルのテストで動作を確かめた。
  • immutable の設計を議論し、ADR 0005 にまとめた。

User #39 11/13 14:18
さて、いまはグリーンですね。リファクタリング?

🤖 Claude

11/13 14:18

今のコードを見直したが、直すべきところは見当たらない。気になりうる点は3つあるが、どれも今は直さないつもりだ。

  • copy() の作り方:copy() の中で一度 Board() で初期盤面を作り、そのあと内部の list を差し替えている。無駄はあるが、コードは短く読みやすい。
  • 番号の変換:穴番号から添字への変換(- 1)が、move_a_stone() の中に2回出てくる。ただ、1つのメソッドの中の隣り合った2行なので、関数に切り出すほどではない。move() でも同じ変換が出てきたら、そこで切り出せばいい。
  • 初期盤面のリテラル:[3, 3, 3, 3, 3, 3, 3, 3] はお題の書き方そのままなので、[3] * 8 などにするより読みやすい。

Refactor はなしにして、TODO を次のように更新するつもりだ。

  • move_a_stone() の項目を [x] にする。
  • copy() の項目も [x] にする。move_a_stone() の中で使われていて、そのテストを通じて動作を確かめられている。

そのあと、穴2のテストの skip を外して、move() に戻る。これでよいか。


User #40 11/13 14:20
番号の変換はすでに気になります。ただ、new.stones_at(1) += 1 みたいに左辺値にする書き方はないと思うんで、まあこれでいいかなあ。それにこのメソッド内に閉じられる可能性はありますね、わかんないけど
いまskip外したらグリーンにならない? それはダメですかね?

🤖 Claude

11/13 14:20

番号の変換と左辺値
Python でも、左辺値に近い書き方はできる。__getitem__ と __setitem__ を定義したクラスなら、new_pits[2] += 1 と書ける。累算代入は「取り出す → 足す → 書き込む」の順に、この2つのメソッドを呼ぶからだ。ここで 1 始まりの番号を受け取れば、- 1 の変換をそのクラスの中に閉じ込められる。

ただ、それには「穴の並び」を表すクラスを新しく作る必要がある。型名の候補として挙がった Pits そのものだ。やっとむの言うとおり、変換は move_a_stone() の中だけで済む可能性もある。だから、今はこのままにしておくのがいいと思う。

skip を外すとグリーンにならないこと
ダメではないと思う。skip を外すのは、Canon TDD の「テストリストから次のテストを選び、失敗するテストを書く」にあたる。テストはすでに書いてあって、一時的に止めていただけだ。止めるのをやめれば Red に戻る。今は Green で直すところもないので、次の Red に進むちょうどいいタイミングだ。

skip を外すときは、# type: ignore[attr-defined] も一緒に消す。そうすると mypy もエラーを出すが、これは前の Red のコミットと同じ状態だ。

手順は次のようにするつもりだ。

  1. TODO の move_a_stone() と copy() を [x] にし、「穴2を選ぶと…」を [O] にする。
  2. skip と # type: ignore を外し、失敗することを確かめて test: でコミットする。

これで進めてよいか。


User #41 11/13 14:22
ああ、すみません勘違いです。skipのままでいいです。次のサイクルで外します
2番の手順で、次のサイクルに入ることになりますね。それでOKです

📝 コミット 4025a59(14:22)

docs: move_a_stone()とcopy()のTODOを完了にする

📝 コミット 210d6f2(14:22)

test: 穴2のテストのskipを外す

--- a/tests/test_board.py
+++ b/tests/test_board.py
@@ -1,5 +1,3 @@
-import pytest
-
 from mancala.board import Board
 
 
@@ -8,9 +6,8 @@ def test_初期盤面はすべての穴に石が3個() -> None:
     assert board.stones() == [3, 3, 3, 3, 3, 3, 3, 3]
 
 
-@pytest.mark.skip(reason="先に move_a_stone() を作る")
 def test_初期盤面から穴2を選ぶと穴3から5に1個ずつ蒔かれる() -> None:
-    board = Board().move(2)  # type: ignore[attr-defined]
+    board = Board().move(2)
     assert board.stones() == [3, 0, 4, 4, 4, 3, 3, 3]

🤖 Claude

11/13 14:22

TODO を更新して、穴2のテストの skip を外し、次のサイクルの Red に入った。

210d6f2 test: 穴2のテストのskipを外す
4025a59 docs: move_a_stone()とcopy()のTODOを完了にする
  • TODO:move_a_stone() と copy() を [x] にした。「初期盤面から1手を指す」と「穴2を選ぶと…」を [O] にした。
  • テスト:skip、# type: ignore、使わなくなった import pytest を消した。
  • Red の確認:pytest は AttributeError: 'Board' object has no attribute 'move' で失敗した(1 failed, 2 passed)。mypy も同じ箇所でエラーを出している。前の Red のコミットと同じ状態だ。ruff は問題なし。
  • worklog:番号の変換と、左辺値の書き方についての話を残した。

次は Green だ。move() の実装は、move_a_stone() を石の数だけ繰り返す形になる。

def move(self, pit: int) -> Board:
    board = self
    to_pit = pit
    for _ in range(self.stones()[pit - 1]):
        to_pit = to_pit + 1
        board = board.move_a_stone(pit, to_pit)
    return board

これは、今の穴2のテストを通すのに必要な範囲の「明白な実装」だ。8から1に回る処理は入れていない。三角測量なら、ここは仮実装(固定値を返す)にする選択肢もある。ただ、move_a_stone() ができたことで、内部表現に触れずにルールだけを書けるようになった。そのため、明白な実装で十分だと考えている。この方針でよいか。


User #42 11/13 14:23
pitはfrom_pitがいいかな、あとpit_noというのはどう思う? ああ、まずはテスト書いてグリーンにした後にしましょう

📝 コミット b83031f(14:23)

feat: 1手を指すmove()をmove_a_stone()の繰り返しで実装

--- a/src/mancala/board.py
+++ b/src/mancala/board.py
@@ -15,3 +15,11 @@ class Board:
         new._stones[from_pit - 1] -= 1
         new._stones[to_pit - 1] += 1
         return new
+
+    def move(self, pit: int) -> Board:
+        board = self
+        to_pit = pit
+        for _ in range(self.stones()[pit - 1]):
+            to_pit = to_pit + 1
+            board = board.move_a_stone(pit, to_pit)
+        return board

🤖 Claude

11/13 14:23

Green にして、コミットした(b83031f)。テストは3件とも通り、ruff と mypy も問題なし。

では名前の話をする。

pit → from_pit
- よい点:move_a_stone(from_pit, to_pit) と名前がそろう。ループの中で to_pit と対になるので、どこからどこへ移すのかが読みやすい。
- 気になる点:move() の引数名は公開インターフェースの一部でもある。お題では、手は「穴を1つ選ぶ」ことだ。クライアントから見ると「選んだ穴」で、「from」は実装の都合から見た名前になる。board.move(from_pit=2) と書かれると、少し実装寄りに見える。

pit_no
- よい点:モデルの図には、番号と石の数を持つ Pit がある。引数が pit だと、将来 Pit のオブジェクトを作ったときに紛らわしくなる。pit_no なら番号(int)だと明確で、お題の「番号は1〜8」とも合う。
- 気になる点:そろえるなら from_pit_no、to_pit_no になり、少し長い。no という略し方を嫌う人もいる(pit_number という選択肢もある)。

自分の考えを言うと、pit_no に賛成だ。今の実装は、穴を番号でしか扱っていない。だから番号であることを名前で示しておくほうがいい。move() の引数は、from_ を付けずに pit_no にするつもりだ。ループの中だけ、to_pit_no と対になる名前があれば読みやすい。

整理するとこうなる。

def move_a_stone(self, from_pit_no: int, to_pit_no: int) -> Board: ...

def move(self, pit_no: int) -> Board:
    board = self
    to_pit_no = pit_no
    for _ in range(self.stones()[pit_no - 1]):
        to_pit_no = to_pit_no + 1
        board = board.move_a_stone(pit_no, to_pit_no)
    return board

ただ、これだと move() の中で pit_no が「選んだ穴」と「石を取り出す穴」の両方の意味を持つ。from_pit を提案したのは、この後者の意味をはっきりさせたかったからだと思う。どう考えているか聞きたい。


User #43 11/13 14:25
fromもnoもつけましょう。長いのは罪ではないです。仕様も「選んだ穴から~」と解釈するのに不自然はない

📝 コミット 866dea5(14:25)

refactor: 穴番号の引数名をfrom_pit_no/to_pit_noにする

--- a/src/mancala/board.py
+++ b/src/mancala/board.py
@@ -10,16 +10,16 @@ class Board:
         new._stones = self._stones.copy()
         return new
 
-    def move_a_stone(self, from_pit: int, to_pit: int) -> Board:
+    def move_a_stone(self, from_pit_no: int, to_pit_no: int) -> Board:
         new = self.copy()
-        new._stones[from_pit - 1] -= 1
-        new._stones[to_pit - 1] += 1
+        new._stones[from_pit_no - 1] -= 1
+        new._stones[to_pit_no - 1] += 1
         return new
 
-    def move(self, pit: int) -> Board:
+    def move(self, from_pit_no: int) -> Board:
         board = self
-        to_pit = pit
-        for _ in range(self.stones()[pit - 1]):
-            to_pit = to_pit + 1
-            board = board.move_a_stone(pit, to_pit)
+        to_pit_no = from_pit_no
+        for _ in range(self.stones()[from_pit_no - 1]):
+            to_pit_no = to_pit_no + 1
+            board = board.move_a_stone(from_pit_no, to_pit_no)
         return board

🤖 Claude

11/13 14:25

move() と move_a_stone() の引数名を from_pit_no と to_pit_no に変えて、refactor: でコミットした(866dea5)。テストは3件とも通り、ruff と mypy も問題なし。

    def move_a_stone(self, from_pit_no: int, to_pit_no: int) -> Board:
        new = self.copy()
        new._stones[from_pit_no - 1] -= 1
        new._stones[to_pit_no - 1] += 1
        return new

    def move(self, from_pit_no: int) -> Board:
        board = self
        to_pit_no = from_pit_no
        for _ in range(self.stones()[from_pit_no - 1]):
            to_pit_no = to_pit_no + 1
            board = board.move_a_stone(from_pit_no, to_pit_no)
        return board

worklog には、move() の実装方針と、名前を決めた理由(no は番号を示す、長いのは罪ではない、from はお題の解釈として自然)を書いた。

気づいたことを1つ伝えておく。番号から添字への変換(- 1)が、move() の中にも出てきた。move() は内部表現に触れないはずだったが、石の数を知るために stones()[from_pit_no - 1] と書いている。この「- 1」は内部の list の添字ではなく、stones() が返す list の添字だ。ただ、穴番号から添字への変換という点では同じことをしている。

TODO の「穴2を選ぶと…」を [x] にして、次の穴5に進むか、ここで何か直すか。


User #44 11/13 14:29
これで、インターフェースとして、穴の指定をintで表現するのではなく、穴のアイデンティティで示すべきと言う根拠ができましたね。Pitオブジェクトを渡すのか、穴の番号を示すenumみたいなものを渡すのか。おそらく8から1に戻るのもまとめてきれいに片付けられるところです。

私のアイデアとしては、Pitオブジェクトを作り、Pitが次のPitを知っているということにする。move()のパラメータはPitオブジェクトを受け取るようにしつつ、Boardにpit(int)を追加して対応する穴を取得できるようにする。まあこれはmove()の内部で呼ぶのでもいいかもしれないんだけど、指定が間違ったときのエラーと責任が明白になるので前者がいいと思います。どうでしょうね?

🤖 Claude

11/13 14:29

方向に賛成する。- 1 の変換と8から1への戻りは、どちらも「穴をただの int で扱っている」ことから来ている。穴にアイデンティティを持たせれば、両方を1か所にまとめられる。Board.pit(int) を入口にする案も、やっとむの言うとおり、01-2 の「存在しない穴は選べない」の責任が Board.pit() にはっきり置かれる点がいいと思う。

そのうえで、決めておきたい点が4つある。

1. Pit は石の数を持つか
持たせず、アイデンティティ(番号と、次の穴)だけにするつもりだ。理由は ADR 0005 との関係だ。Board は手を指すたびに新しい盤面を返す。Pit が石の数を持つと、古い盤面から取った Pit を新しい盤面に渡したときに、どちらの盤面の穴なのかが曖昧になる。Pit がどの盤面にも属さない値なら、board.pit(2) で取った Pit は、どの盤面でも「穴2」として通用する。

モデル図では Pit が石の数を持っているので、この場合は図も直すことになる。

2. クラスか enum か
- enum:8つの穴が型として固定される。Pit(9) は作ることさえできない。ただ、そうなると「8つ」という知識が Pit の型の側に入り、Board.pit() はほぼ変換するだけになる。
- 値オブジェクトのクラス(frozen dataclass など):Pit(9) 自体は作れてしまう。そのぶん、範囲の検証と「8つ」という知識を Board 側に置ける。

やっとむの「エラーの責任を Board.pit() に置く」という考えに合うのは、クラスのほうだと思う。

3. クライアントの書き方
テストはこうなる。

board = Board()
board = board.move(board.pit(2))

今の Board().move(2) より1段階増える。エラーの責任をはっきりさせる代わりに、クライアントの手間が増える。この代償は受け入れる、という理解でよいか。

4. TDD での進め方
2つに分けて考えている。
- Refactor(振る舞いを変えない):Pit を導入して、move() の引数を Pit に変える。テストの書き方も変わる。
- 新しい振る舞い:8の次が1になることは、まだどのテストにも出てこない。だから next() の8→1は、Refactor の中で一緒に入れない。TODO の穴7や穴8のテストで Red にしてから入れる。

1〜4について、やっとむの考えを聞きたい。


User #45 11/13 14:32
1->同意します。listのインデックスを持っていて、石の数自体はいまのlistで持つ形にしておいて、いまはいいんじゃないかな。あるいはBoardに、Pitオブジェクトとインデックスのマップを持つ
2->知識をコードにするかオブジェクトにするかですね。んー。なんとなく、enumでいいんじゃないかなあ。とりあえずですけど
3->YES。いちど変数に入れるイメージでいました。そうすると、番号が違えばその行で例外になる
4->LGTM

📝 コミット 2234d79(14:33)

refactor: 穴をintではなくPitのenumで指定する

Board.pit(int)でPitを取得し、move()とmove_a_stone()はPitを受け取る。 穴番号から内部のlistの添字への変換はBoard._index()に閉じ込める。

--- a/src/mancala/board.py
+++ b/src/mancala/board.py
@@ -1,3 +1,6 @@
+from mancala.pit import Pit
+
+
 class Board:
     def __init__(self) -> None:
         self._stones = [3, 3, 3, 3, 3, 3, 3, 3]
@@ -5,21 +8,27 @@ class Board:
     def stones(self) -> list[int]:
         return self._stones.copy()
 
+    def pit(self, pit_no: int) -> Pit:
+        return Pit(pit_no)
+
     def copy(self) -> Board:
         new = Board()
         new._stones = self._stones.copy()
         return new
 
-    def move_a_stone(self, from_pit_no: int, to_pit_no: int) -> Board:
+    def move_a_stone(self, from_pit: Pit, to_pit: Pit) -> Board:
         new = self.copy()
-        new._stones[from_pit_no - 1] -= 1
-        new._stones[to_pit_no - 1] += 1
+        new._stones[self._index(from_pit)] -= 1
+        new._stones[self._index(to_pit)] += 1
         return new
 
-    def move(self, from_pit_no: int) -> Board:
+    def move(self, from_pit: Pit) -> Board:
         board = self
-        to_pit_no = from_pit_no
-        for _ in range(self.stones()[from_pit_no - 1]):
-            to_pit_no = to_pit_no + 1
-            board = board.move_a_stone(from_pit_no, to_pit_no)
+        to_pit = from_pit
+        for _ in range(self._stones[self._index(from_pit)]):
+            to_pit = Pit(to_pit.value + 1)
+            board = board.move_a_stone(from_pit, to_pit)
         return board
+
+    def _index(self, pit: Pit) -> int:
+        return pit.value - 1
--- /dev/null
+++ b/src/mancala/pit.py
@@ -0,0 +1,12 @@
+from enum import Enum
+
+
+class Pit(Enum):
+    PIT_1 = 1
+    PIT_2 = 2
+    PIT_3 = 3
+    PIT_4 = 4
+    PIT_5 = 5
+    PIT_6 = 6
+    PIT_7 = 7
+    PIT_8 = 8
--- a/tests/test_board.py
+++ b/tests/test_board.py
@@ -7,10 +7,15 @@ def test_初期盤面はすべての穴に石が3個() -> None:
 
 
 def test_初期盤面から穴2を選ぶと穴3から5に1個ずつ蒔かれる() -> None:
-    board = Board().move(2)
+    board = Board()
+    pit = board.pit(2)
+    board = board.move(pit)
     assert board.stones() == [3, 0, 4, 4, 4, 3, 3, 3]
 
 
 def test_初期盤面で穴2から穴3に石を1つ移す() -> None:
-    board = Board().move_a_stone(2, 3)
+    board = Board()
+    from_pit = board.pit(2)
+    to_pit = board.pit(3)
+    board = board.move_a_stone(from_pit, to_pit)
     assert board.stones() == [3, 2, 4, 3, 3, 3, 3, 3]

📝 コミット 990cd05(14:33)

docs: 穴2のTODOを完了にし、Pitの導入をモデルとworklogに反映する

docs/model.md の図(この時点)

classDiagram
    class Board {
        stones : int[8]
    }
    class Pit {
        <<enumeration>>
        number : 1..8
    }
    class Move
    Board ..> Pit : 穴ごとの石の数を持つ
    Move ..> Board
    Move ..> Pit

🤖 Claude

11/13 14:33

Pit を導入して、Refactor としてコミットした(2234d79)。テストは3件とも通り、ruff と mypy も問題なし。

src/mancala/pit.py

class Pit(Enum):
    PIT_1 = 1
    ...
    PIT_8 = 8

Board の変更
- pit(pit_no: int) -> Pit を追加した。今は Pit(pit_no) を返すだけだ。
- move() と move_a_stone() は Pit を受け取る。引数名は from_pit、to_pit にした。int ではなくなったので、_no は外した。
- 番号から内部の list の添字への変換は、非公開の _index(pit) に閉じ込めた。move() も stones()[... - 1] ではなく、これを使う。
- 次の穴は、まだ Pit(to_pit.value + 1) で求めている。next() と8→1は、決めたとおり Red から入れる。

テストは、pit = board.pit(2) と一度変数に入れる書き方にした。

ドキュメントも更新してコミットした(990cd05)。
- TODO:「穴2を選ぶと…」を [x] にした。
- モデル図:Pit を enum にして、石の数を外した。石の数は Board が持つ形にした。
- worklog:今回の議論と、決めたことを書いた。

1点だけ、やっとむの選択肢から自分で選んだところがある。1番の「Pit が list の添字を持つ」と「Board がマップを持つ」のうち、どちらでもなく、enum の値を番号にして、添字への変換を Board の _index() に置いた。Pit に list の添字を持たせると、Board の内部表現の知識が Pit に漏れるからだ。Board がマップを持つ形と考え方は同じで、マップの代わりに計算している。違うなら直す。

Board.pit(9) は、今は enum の ValueError がそのまま出る。これをどう表すかは、01-2 のテストで決める。


User #46 11/13 14:37
ファイルが細かすぎますね。Pitはboard.pyに入れておきましょう。あるいはmancala.pyにしてもいいかもしれない。
pit()の実装が思ったのと違った。pit(1) is pit(1)、つまり同一オブジェクトになるつもりだった。アイデンティティというのはそういう意味。仮実装ということ? ああ、enumaじゃなくてオブジェクトというのが、そういう意味でしたかね?

def _index(self, pit):
  return self._pit_index_map[pit]

こう書くイメージでした。

📝 コミット 3af78d5(14:37)

refactor: Pitをboard.pyに移す

--- a/src/mancala/board.py
+++ b/src/mancala/board.py
@@ -1,4 +1,15 @@
-from mancala.pit import Pit
+from enum import Enum
+
+
+class Pit(Enum):
+    PIT_1 = 1
+    PIT_2 = 2
+    PIT_3 = 3
+    PIT_4 = 4
+    PIT_5 = 5
+    PIT_6 = 6
+    PIT_7 = 7
+    PIT_8 = 8
 
 
 class Board:
--- a/src/mancala/pit.py
+++ /dev/null
@@ -1,12 +0,0 @@
-from enum import Enum
-
-
-class Pit(Enum):
-    PIT_1 = 1
-    PIT_2 = 2
-    PIT_3 = 3
-    PIT_4 = 4
-    PIT_5 = 5
-    PIT_6 = 6
-    PIT_7 = 7
-    PIT_8 = 8

📝 コミット 553dc60(14:37)

refactor: 穴から添字への変換をマップで行う

--- a/src/mancala/board.py
+++ b/src/mancala/board.py
@@ -13,6 +13,8 @@ class Pit(Enum):
 
 
 class Board:
+    _pit_index_map = {pit: index for index, pit in enumerate(Pit)}
+
     def __init__(self) -> None:
         self._stones = [3, 3, 3, 3, 3, 3, 3, 3]
 
@@ -42,4 +44,4 @@ class Board:
         return board
 
     def _index(self, pit: Pit) -> int:
-        return pit.value - 1
+        return self._pit_index_map[pit]

🤖 Claude

11/13 14:38

The gate worked this time. Apply the formatter and commit.

📝 コミット 5a11dae(14:38)

fix: 添字のマップをClassVarとして注釈する

--- a/src/mancala/board.py
+++ b/src/mancala/board.py
@@ -1,4 +1,5 @@
 from enum import Enum
+from typing import ClassVar
 
 
 class Pit(Enum):
@@ -13,7 +14,9 @@ class Pit(Enum):
 
 
 class Board:
-    _pit_index_map = {pit: index for index, pit in enumerate(Pit)}
+    _pit_index_map: ClassVar[dict[Pit, int]] = {
+        pit: index for index, pit in enumerate(Pit)
+    }
 
     def __init__(self) -> None:
         self._stones = [3, 3, 3, 3, 3, 3, 3, 3]

📝 コミット 59f4925(14:38)

docs: Pitのアイデンティティと添字のマップについてworklogに残す

指摘された3点を直した。

pit(1) is pit(1) について
今の実装でも、同じ番号なら同一オブジェクトになる。仮実装ではない。enum のメンバーはシングルトンで、Pit(1) は何度呼んでも同じ Pit.PIT_1 を返すからだ。実際に試した結果は次のとおり。

  • b1.pit(1) is b1.pit(1) → True
  • b1.pit(1) is b2.pit(1) → True(別の Board から取っても同一)
  • b1.pit(1) is b1.pit(2) → False

前回「クラスか enum か」と聞いたときの「値オブジェクトのクラス」は、frozen dataclass のようなものを指していた。こちらは == では等しくなるが、is で同一にはならない。やっとむの言う「アイデンティティ」には、enum のほうが合っていた。

コミット

59f4925 docs: Pitのアイデンティティと添字のマップについてworklogに残す
5a11dae fix: 添字のマップをClassVarとして注釈する
553dc60 refactor: 穴から添字への変換をマップで行う
3af78d5 refactor: Pitをboard.pyに移す
  • Pit の置き場所:pit.py を消して、board.py に入れた。
  • 添字への変換:_index() を self._pit_index_map[pit] にした。マップはすべての盤面で同じなので、クラス属性として1つだけ持たせている。

また同じ失敗をした
553dc60 は、ruff のエラー(RUF012:変更可能なクラス属性には ClassVar の注釈が要る)が出ているのに、コミットしてしまった。前回の mypy と同じで、コマンドを ; でつないでいたのが原因だ。

ClassVar の注釈を付けて、fix: でコミットした(5a11dae)。これ以降は、チェックをすべて && でつなぎ、全部通ったときだけコミットする。修正のコミットはこの方法で行い、フォーマットの違反でコミットが止まることも確かめた。同じことを繰り返さないよう、自分用のメモにも残した。

1つ聞きたい。「pit(1) is pit(1)」は、やっとむが意図して決めた設計だ。お題の「決めたことはテストとして残す」に従えば、テストにしておく候補になる。TODO に足すか。


User #47 11/13 14:40
そうですね、TODOに入れておきましょう。あまり重要ではなさそうな気はします。

📝 コミット f4e1c72(14:40)

docs: 穴のアイデンティティのテストをTODOに足す

🤖 Claude

11/13 14:40

TODO に足して、コミットした(f4e1c72)。

- [ ] 同じ番号の穴は同一オブジェクト(pit(1) is pit(1)。自分で決めた仕様、重要度は低め)

置いた場所は、immutable の項目の直後、01-2 の前だ。やっとむが言ったとおり、重要度は低めと書き添えた。


User #48 11/13 14:41
テストはグリーン、リファクタリングもしたところ、ということになるかな? 他にはあるかしら

🤖 Claude

11/13 14:41

そうだ。穴2のサイクルは Green と Refactor まで終わっている。ブランチは step-01-move で、ワークスペースはクリーンだ。

ほかに直す候補になりそうなものを見直した。どれも、今すぐ直す必要はないと思う。

  • Pit(to_pit.value + 1):move() の中で、まだ enum の値を使って足し算をしている。これは「8の次は1」と一緒に next() へ置き換える予定のところなので、穴7・穴8の Red で扱う。
  • Board.pit() が self を使っていない:今は Pit(pit_no) を返すだけで、盤面の状態に関係しない。ただ、01-2 で範囲の検証が入れば、Board が「穴は8つ」という知識を持つ場所になる。それまではこのままでいい。
  • テストの並び順:テストファイルでは move() のテストが move_a_stone() のテストより前にある。TODO の順(石を1つ移す → 1手を指す)とは逆だ。読む順として気になるなら入れ替えるが、動作には関係しない。

User #49 11/13 14:43
これで2時間終了となります。ありがとうございました。
休憩を入れてから、ちょっと感想戦をしましょう。

🤖 Claude

11/13 14:43

2時間おつかれさま。ありがとう。

今の状態を書いておく。

  • 作業ブランチ step-01-move は、01-1 の途中なので develop にマージしていない。ワークスペースはクリーンだ。
  • ADR 0001 では「main は作業セッションが終わるまで触らない」と決めてある。セッションの区切りで main をどうするかは、感想戦のときに決めればいい。

ゆっくり休んで。感想戦を楽しみにしている。


User #50 11/13 14:52
さてあらためて、おつかれさまでした。
ポモドーロ4周ですけど、多少あふれてるので正味2時間あったとおもいますが、進まなかったですねえ。
前半は進め方、環境の整備、仕様の把握やモデリングでだいぶ時間を使いました。
TDDサイクルに入ってからは、設計の議論をずいぶんしていたと思います。
もうちょっとテストを書き進めてから設計の話をしたらよかったかなあとも思いますし、
いっぽうでそろそろスピードを出せそうな感じに、実装のためのパーツがそろってきたところでもありました。
あと終盤のPitのところは、ちょっと話がモツれてしまったかもしれません。
私が自分でテスト書いたりすればよかったかもですね。
mypyのエラーの扱いも、あまり本質的じゃないところでしたね。
途中、コードやテストは見ましたが、直接編集はしませんでした。
ドキュメント類もさっと見た程度でした。
worklogはまだ見てないですが、思い出すのに役立つ内容になってるかな。

🤖 Claude

11/13 14:53

おつかれさまでした。数字で振り返ると、コミットは38件、テストは3件、お題の例を通したのは穴2の1件だけだった。

やっとむの振り返りについて、自分の側から見えたことを書く。

設計の議論が多かったこと
自分の進め方も議論を増やしていた。ほぼ毎回、選択肢と理由と複数の質問を返していた。グローバルの CLAUDE.md の「質問を多くする」「選択肢には理由を添える」に従った結果ではある。ただ、そのたびに論点が2〜4個増えた。たとえば、immutable のテストを足す話、型名 Pits の話、pit(1) is pit(1) をテストにする話は、どれも自分が持ち出したものだ。どれも間違いではないが、テストを書き進める流れを止める方向に働いていた。

Pit のところがもつれた理由
原因の大半は自分の側にあると思う。
- やっとむが言った「アイデンティティ」を、「石の数を持たず、番号だけを持つ」という意味に受け取っていた。pit(1) is pit(1) という、同一オブジェクトの意味で受け取っていなかった。
- 「クラスか enum か」の比較を、検証の責任をどこに置くかという観点で示した。同一性の観点が抜けていた。
- やっとむが挙げた2択(Pit が添字を持つか、Board がマップを持つか)を確認せず、自分で第3の形を選んで実装した。

結果として、実装したあとに「思ったのと違う」となって、手戻りが出た。

mypy の件
本質的でない話に時間を使わせたのは、自分のミスが原因だ。チェックが失敗したままコミットしたことが2回あり、fix: のコミットと説明でやり取りが増えた。skip のテストを mypy が検査するという件は、skip を使ったことから出た副作用でもあった。

やっとむが自分でテストを書くこと
意図を文章で伝え、自分がそれを解釈してコードにする形だと、解釈のずれが入り込む余地がある。Pit のもつれはまさにそれだった。テストのコードそのものを書いてもらえば、意図がそのままコードに残る。

worklog は思い出すのに役立つか
流れを追うことと、決めた理由を思い出すことには役立つと思う。ただ、自分で読み返して気づいた問題が3つある。
- 「13:35頃 テストリスト」の節が「13:20頃 言語と環境」より前にあって、時刻の順になっていない。どちらの時刻も記録したものではなく推定だ。
- 「14:10頃」の節が長く、インターフェース、move_a_stone()、immutable、mypy の件が1つの節に入っている。
- 自分が書いているので、自分が持ち出した論点と、やっとむが考えたことが区別されないまま並んでいる箇所がある。

聞いてみたいことが1つある。今日の設計の議論のうち、やっとむから見て時間を使った価値があったのはどれだったか。


User #51 11/13 14:56
そういえば今が14:54で、14:55頃というのは微妙ですね。とりあえず、いったん終わりにしたというのはworklogに書いておいてください。14:50頃だったはず

質問に答える前に、わたしの入力をいったん措いてあなたの感想とか印象とかを教えてください。

📝 コミット 2020a5a(14:56)

docs: セッションをいったん終了したことをworklogに残す

🤖 Claude

11/13 14:56

worklog に「14:50頃 いったん終了」を追記して、コミットした(2020a5a)。

なお、worklog の「14:55頃」の見出しは、実際の時刻を確かめずに推定で付けたものだ。セッションが14:50頃に終わったのなら、内容とも合っていない。直すかどうかは、やっとむに任せる。


ここから、やっとむの振り返りを抜きにした、自分の感想だ。

いちばん印象に残ったのは move_a_stone()
三角測量を考えていたとき、自分は「仮実装のために Board をどう作るか」で止まっていた。コンストラクタを公開するか、内部用のメソッドにするか、という話だ。やっとむの「石を1つ移す操作を基本にして、move() はルールだけを表す」という案は、その問いの立て方そのものを変えていた。内部表現を遅らせる、という目的にも合っていた。自分からは出てこなかった案で、ペアの相手がいる意味をいちばん感じたところだった。

設計は、テストからというより議論から出てきた
今日の設計判断の多くは、テストを書いて痛みを感じたからではなく、話し合いの中で先に出てきた。Pit の導入は - 1 の重複がきっかけで根拠はあったが、8→1 のテストを書く前に入っている。悪いことではないが、Canon TDD の「テストに設計を引き出させる」とは少し違う進み方だったと思う。

自分の役割は、ペアというより書記に近かった
記録、コミット、TODO の更新、選択肢の整理をずっとやっていた。コードを提案して議論の材料にする場面は少なかった。ADR が5本、worklog が約120行に対して、プロダクトコードは50行ほどだ。この比率が演習の目的(認知負債を減らす)に合っていたのか、記録が重すぎたのかは、自分では判断がつかない。

1サイクルあたりの手間が大きかった
小さな変更でも、TODO の更新、worklog の追記、プレフィックス付きのコミット、ときにはブランチ操作がついてくる。決めたルールはどれも妥当だったが、積み重なると、テストを書いている時間の割合が下がっていた。

自分のミスが、やっとむの注意を余計に使わせた
チェックが失敗したままのコミットが2回あった。ADR に議論していない理由を書いたことも2回あった。どれも小さなミスだが、そのたびに、やっとむは自分の出力を確かめなければならなくなる。任せられる範囲を狭めてしまったと思う。


User #52 11/13 15:10
worklogの時刻だけ変えました。コミットしておいてください。また途中とは言え終了するので、developにマージしておいてください。テストリストがあるから大丈夫。

move_a_stone()は、いちばんプリミティブな操作が何かというところから自然に出てきたものですし、内部表現を後回しにしたいなあという怠惰さもありました。生成AIはあまり怠惰になれないですね。また直感として、穴の状態ではなく石の状態(居場所)が本質じゃないかなと思っていたのもあります。先に進まないと、当たりか外れかわかりません。

テストを書いてから設計にならなかったのは、私が先走ったところが大きいです。とはいえ、テストなしで決め打ちにはならなかったと思っていて、議論した上で、検証するためにテストを実装を進めるという順序にはできていたんじゃないかなあ。

手間が大きかったのは、まさに助けられたところですね。人間がすべてやるのでは時間がかかってやってられないですが、体感としてはとてもスムーズでした。あまりマジメに読んでいないというのもありますけれど。とにかく、ソロ作業の効果を高めるという点では非常に助かりました、助かることが確認できました。

ミスについてはまあそんなものでしょう。

さて質問に答えてみると、どうでしょうねえ。議論といってもわりと私が思いついたことを説明してやってもらうという、議論そのものを戦わせた場面は少なかったような感じがします。あなたが質問したりなにか提示し、私がなにか言って、それで進むという感じ。言語化したのがよい結果になったと考えると、最初の仕様把握やモデリングは時間をかけた価値があった気がします。モデルそのものが役立ったかは、いまの段階では微妙ですが、モデリングの過程は有意義でした。それとイミュータブルの議論は、新たな観点も得られて、良かったと思います。それはあなたが出してくれたアイデアによるものですね。

📝 コミット 9c60d4e(15:10)

docs: worklogの時刻を直す

📝 コミット bcf214e(15:10)

Merge branch 'step-01-move' into develop

🤖 Claude

11/13 15:10

worklog の時刻の修正を docs: でコミットした(9c60d4e)。そのあと step-01-move を develop にマージした(bcf214e)。今は develop にいて、マージ後もテストは3件とも通っている。main は ADR 0001 のとおり触っていない。

worklog の「14:50頃 いったん終了」には、「develop にマージしていない」と書いたままになっている。終了した時点の記録としては正しいので、そのままにしてある。


感想を聞いて思ったことを書く。

怠惰さについて
それは当たっていると思う。自分は手間を惜しまないぶん、「後回しにしたいから、もっと小さな操作を探す」という動機が生まれにくい。仮実装のために Board の作り方を考えていたのは、まさに「目の前の問題を手間をかけて解く」方向だった。怠惰が設計の推進力になるというのは、プログラマの三大美徳(Larry Wall)そのものだ。「石の居場所が本質ではないか」という直感も含めて、当たりか外れかは先に進んでみないとわからない、というのはそのとおりだと思う。

議論の順序について
やっとむの言うとおりだ。テストより前に設計の話は出ていたが、決め打ちで実装したことはない。move_a_stone() も Pit も、議論のあとに、テストで確かめられる形で入れている。自分が言った「テストから設計が出てこなかった」は、言いすぎだった。

議論を戦わせなかったことについて
自分の側から見ても、そうだったと思う。自分は選択肢と理由を出したが、やっとむが方向を示したあとは、ほぼ同意して進めていた。反対意見をはっきり言った場面はなかった。

たとえば board.pit(2) を一度変数に入れる書き方は、クライアントの手間が増えることを指摘しただけで、それ以上押さなかった。Pit を 8→1 のテストより前に入れることも、自分は疑問を言っていない。今日の流れでは、それで支障はなかった。ただ、議論として深まる機会を自分が作らなかった、とは言えると思う。

immutable の議論
役に立ったのならよかった。あれは、案 B を出したときに「元の盤面は変わらない」を約束としてテストに残すか、と聞いたところから広がった話だった。やっとむが「真に immutable」と「振る舞いとして immutable」を分けたことで、ADR 0005 の「B→A は容易、A→B は影響が大きい」という判断の軸が出てきた。あそこは、自分の問いとやっとむの整理がうまく噛み合ったところだったと思う。

TDDBC Sendai 11thに参加しました

10/24の土曜日、TDDBC Sendai 11thに行ってきました。TDDBC (テスト駆動開発ブートキャンプ) はテスト駆動開発の基礎をハンズオンでみんなで学ぼうというコミュニティイベントです。新型コロナで途切れましたが以前からよく行われていたもので、仙台では特に活発で毎年行われていたそうです。とはいえやはり新型コロナの影響や、運営メンバーにお子さんが生まれたなどの事情もあって、何年かぶりでした。

tddbc.connpass.com

TDDBCの流れは、午前は基調講演でTDDの解説があり、午後は参加者がペアを組んでペアプログラミングでハンズオンするというものです。基調講演は t-wadaさんによるものですが、今回は「TDDのことはYouTubeの基調講演動画を見てきてください」という前提で、生成AIの動向や整理をした新鮮な内容でした。最近の t-wada さんの講演で見覚えあるページもありつつ、現代のTDDの位置づけを整理するものです。そのうえで今日の説明として、今回は実験回であり参加者は実験台ですということで、TDDハンズオンで生成AIを使ってもよいことになりました。TDDBCはテストコードとプロダクトコードをいずれも丁寧に書くこと、リファクタリングを通じてコードをきれいにすることを通じて、プログラマーが技法と「きれいなコード」の理解を深めるのを大事にしています。とはいえ、それをすべて手で書くのが現実的ではなくなってしまったいま、和田さんもよりよいやり方を探っているのだと思います。

ハンズオンでは参加者がペアを組みます。私もペアに入らせてもらいました。普段コードを書かない方と組んだので、あえて丁寧に古典的TDDのステップを踏みつつ、コードが怪しいところはチャットでAIに聞くというくらいの、生成AI利用低めの進め方になりました。進みはゆっくりでしたが、TDDの所作や考え方、また自動テストをメンテナンスしてくという考え方に慣れてもらえたようです。私も基本を紹介しつつ丁寧にステップを踏んでいけたのが楽しく、若者のPCの文字の小ささと戦う経験でした (まだ、まだ大丈夫!)。

t-wadaさんの講演でも、TDDは2025年から急速に話題になり、エージェントが書くなり進めるなり広く使われるようになっています。和田さん曰く「プロンプトに「t-wadaのTDD」と書くとよいと言われていたが、最近では「red/green TDD」と書くと効果的なTDDをやってくれるようだ」とのこと。ハンズオンでも、AIエージェントのアウトプットを人間が見るポイントとしてのテスト、それを学ぶのにTDDが役立つという実感もあり、他の参加者からもそんな声がふりかえりで出ていました。

ペアプロやモブプロとAIエージェンティック開発の親和性の良さも評価されていたようです。人間1人と生成AIだと、表面的には話をしているような印象も受けますが、むしろそれぞれが一方通行の発言をしながら一本道で作業が進んでいくものだと感じます。人間2人と生成AIにすると、人間どうしで理解を確かめたり方向を合わせたり知らない点を見つけたり、生成AIの発言や出力を見ながら話ができたりして、必要最低限の多様性が生まれるのではないかと思いました。基調講演にもあった「認知負債」に対して、人間が人間を通じて理解、把握するアプローチになりそうです。

ハンズオンの時間中、t-wada さんは何をしてるのかなと思ったらソロプログラミングでAIエージェントとTDDしていて、今日のお題 (t-wada さんも初見) に取り組んでいたそうです。その記録というか生ログを公開してくれています。

t-wada.hatenablog.jp

仙台の運営のみなさん、参加者のみなさん、ありがとうございました。久しぶりで、とても楽しいTDDBCでした。来年も行きたいです! 生成AIを利用した開発の中でTDDが再注目されているらしいので、各地のTDDBCもまた盛り上がるといいなあと思います。

本記事では生成AIを利用していません。

テストの「成功」とは? TDDの成功って?

みなさん、TDDや、それ以外のテスト、CIで流したテストとか、さらに手動でテストするとき「テストが成功する」って言いますか?

先日、テスト駆動開発 (TDD) の話題で「テストがグリーンだと通った、レッドだと落ちたって言うよね。テストが失敗するも言う。でも成功するって、実際あんまり言わなくない?」という話に、テスト駆動飲み会のひとびととなりました。

言う言わないは単なる習慣の問題で、「テストが成功する」という表現が意味不明かというとそんなことはない。間違いかというと、いや合ってる。合ってると思う。思うけどなあ。んー、あれ?

今回はそういう話です。

※なお記事作成に生成AIは使用していません (レビューには使ってます)。

どんなテストがいつ成功するのか

ふつうに「成功する」と言えそうなのが、CI/CDパイプラインでリリースブランチのテストを流したときとか、開発中ブランチをメインブランチにマージするためのテストを流すときなどですね。すべてグリーンでパイプラインが完了したら「成功した」と思ったり言ったりしそうです。もっともこれは、テストが成功したというよりは、リリース準備が成功した、マージが成功したという表現をしたくなる気もします。やりたい作業があって、その中にテストも含まれているけれど、全体がうまくいったというニュアンスです。

じゃあもう少し先のタイミング、大規模なリリースに向け終盤でテストを人がやるときはどうでしょう。業界にもよりますがシステムテストとかユーザー受け入れテストとか呼ばれるところで、「なにも問題が見つからなかったのでテストは成功だった」と言ったら、これはちょっとヤバイですね。大規模な追加変更に対する大規模なテストは、なんらかの問題を見つけるほうが当たり前です。これは前提として、なんらかの問題を開発中に作り込んでしまうのが当たり前、あるいは仕様やユーザー利用について想定外があって当たり前と考えているためです。だからテストして見つけるんだと。

テストで問題が見つからなかったら、それは見つからなかっただけであって、問題は隠れて残っているというわけです。こうした場合は「テストで十分に問題が見つけられた (そして直せた) から成功」と思うのが自然です。

ではもっと手前、開発途中で自動テストを流したときはどうでしょう。書いた自動テストを実行して、オールグリーンになった、テストが通った。これは「テスト成功」? どうでしょう、自分が感じている自信によると思うんですよね。バッチリ書き上げた、エッジケースも例外も完全に設計通りに完成したぜ、と思っているなら「テスト成功」で良さそうです。

そうではなくて、とりあえず正常系だけだいたい動くようになったんだよね、まだエラーチェック入れてないし、考え漏れもしてそうだなあ。。。というところでテストを実行していくつか落ちたら、期待通り想定通り思った通り。「成功」という言葉が出てくるかわかりませんが、じゃあ残りも開発進めましょうという気持ちになります。

もしここで、まだ開発ぜんぜん途中なのに、流したらテストがぜんぶ通った! あれっ、これでもう完成だっけ? いやそんなはずないのに、テストで引っかからないのか、このテスト大丈夫かなあ。。。これはちょっと、テスト成功とは思わないですね。誰が書いたテストにせよ、あーテスト足りてないじゃん。。。というなんか負け感を受けます。成功・失敗の話をしてるのに「負け」とか言い出して面倒くさくするなよ。。。

レッド・グリーンは結果、失敗・成功は評価

こう考えていくと、テストが通る、グリーンになるというのは単なる事実です。テストが落ちる、レッドになるのも客観的な結果、アウトプットです。それに対して「成功」「失敗」は、人の主観というか、テストを実行している目的に対する評価のようです。成功=思い通りに進んだ、期待した結果になった、必要な情報を得られた、納得・満足した。

テスト駆動開発ではこの違いがとても明確になります。レッド・グリーン・リファクタリングのサイクルをたどる中で、レッドになるときはレッドが期待通り=成功、グリーンにするときはグリーンが期待通り=成功ですね。成功になったら次のステップに進みます。リファクタリングは? リファクタリング中にレッドにしちゃうのは、一種の失敗ですが、コードとテストがきれいになり、かつグリーン=成功かな。

こう整理すると、TDDを実践するときはテスト実行前に結果を予想せよと言われるのも、大事なことだと分かります。漫然とテストを流して結果が出ただけでは、成功なのか失敗なのか分からない。いま何をしていて何を期待しているのかわからなければ、成功かどうかわからないし、次にどうしたらいいかもわからなくなってしまいます。逆に言うと、いま書いたコードやテストが「成功」かどうかすぐわかるというのが、TDDの魅力でもありますね。

これ以上話を進めると、蛇足で一般化しすぎにはなるんですが、ひとことだけ。TDDで書いたコードやテストが「失敗」したら、つまり想定外の結果になったら、これは勘違いや見落とし、なにか知らないことを発見するチャンスです。発見から学べば大きな意味では「成功」。TDDのサイクルには成功しかないんですね。

おまけ

英語では、テストが通る/落ちるは pass / fail。一般に成功/失敗は success / failure。「失敗する」と動詞だと fail や failed になる。つまり英語では、落ちると失敗するは、見た目が似てたりそもそも同じ言葉になるんですねえ。日本語で「テストが失敗する」は自然に聞こえるのも、このへんが絡んでるんでしょうか。

『アジャイルを飯の種にして生きる人々』感想文 その2・有名人はなぜ有名なのかという話

『アジャイルを飯の種にして生きる人々』(匿名アジャイルプラクティショナー 著)について書く2回目です。この本について批判的な評が目に付くのですが、私としてはそんなことはない、現実に存在する影響を与える問題について実質的な提起をしていると思いました。とはいえ著者の方には申し訳ないが読みにくさもあり熟読はできていません。なので書評ではなく感想文という形で、読んで考えたことを書いています。

1回目では、アジャイル界隈の先駆者や有名人が、依頼側が有名さから期待する実際の仕事での成果を、必ずしも出せていないという問題提起を紹介しました。またここでいう先駆者や有名人と著者が考えている人は、本書を読んで受ける印象よりも、だいぶ範囲が広く人数として多いという、私の見方も提示しました。(ところで後から考えたのですが、有名だけど成果が出ないと表現するより、仕事上の実績および評価が透明でないと考えたほうが、一歩真因に近づけそうです。)

長いので最初に要約、というよりは書くときに考えた全体構成です。これには生成AIを使っていませんし、本記事のどこにも生成AIは使っていません。

全体構成: 本書によれば有名人は有名なだけでなく、有名人ポジションを維持・強化している。これはその人の意志とも限らず、構造的な面がある。残念ながらこの構造が問題も生んでおり、本書で指摘している (今回の記事では省く)。本書の内容から外れるが、私は有名人が有名になったのは運が良かったからだと考えればいいと思う。そんなに運がよくなかった人にもチャンスは公平にあるべきだ。

著者は本書の多くの部分を費やして、有名人がどうやって有名であるという立場を生かし、維持しているかを構造的に説明しようとしています。その内容があんまりにも多岐にわたっているのと、具体性・客観性を欠くものが多くて (中には「噂される」とかまである) それは著者の想像に過ぎなくないですかね、とも思います。そういう想像をしている著者には妬みや嫉みがあるんだ、と読み取る人がいるのも、仕方ないかもしれません。

とはいえ著者は有名人が数多くの貢献や実績を残しアジャイルの普及とコミュニティの発展に寄与してきたことを、繰り返し認めています。それと同時に、有名人が高額の収入を得ているとしても (著者はそう信じていると私は思います) そのこと自体を指弾しているわけではありません。(うがって見れば「自分だって高額収入ほしい」と著者は思っているかもしれません。)

本書では単純に「稼ぐ=悪」という短絡的な二項対立には陥りたくない。アジャイルを広めたことで社会や組織に大きな貢献を果たしている人々もたくさんいる (Kindle位置118)

本書は構造への批判に多くの紙幅を割いた。しかし、その構造の中にも確かに善意は存在する。問題なのは善意がないことではなく、善意が構造的力学によって歪められ、消費されることなのだ。(Kindle位置4045)

では著者は何を言っているのかというと、有名人にいろいろと集中することで害があったり、若手のチャンスが失われたり、コミュニティのありようが歪んだりするという構造的に起きる問題を紹介しています。そして本書では、有名人にいろいろと集中していく仕組みを紐解こうとしています。いろいろ、というのは、仕事や案件の機会、登壇機会、翻訳や執筆の機会、メディア露出機会、コミュニティやイベントの発言権や決定権、SNSのフォロワーなどです。

私なりに著者の主張を解釈して、有名人がどうやって立場を作り、維持しているのか抽出してみました。抽出としては不完全で、著者が重視している点を見落としていそうな気はします。

  • アジャイル普及の初期に実績を出した人が、講演、執筆、SNSフォロワー増などの機会を多く得て、有名になる。
  • 有名になると、業界の中で立場を作って維持できるようになり、権威化していく。
  • 権威化した有名人どうしはお互いに立場や仕事を安定させるべく、結託している。
  • 新参の人の貢献や新しいコミュニティに、有名人が自分の名前、自分のラベルをつけて立場維持に役立てている。

うーんそうかなあ。こういうメカニズムがあるのだと言われると、それはないだろうと言いたい。こういう傾向があるんだという主張なら、賛成します。個別のできごととして見たことは、私もたしかにあります。意図的に作戦として継続してやっている人がいるのかというと、たぶんいると思います。

ネズミ講みたいなメカニズム、スキームが浸透しているという著者の主張には、私は否定の立場です。しかしそういう傾向があるとか、それを強める仕組みを導入しているという主張は、部分的に賛成です。部分的というのは、それと反対の傾向もやはり仕組みとして導入しているためです。広く平等に参画の機会を作るとか、初登壇の人をサポートする体制を作ってきたとか (有名人が引っ張り上げるというのではなく、です)、翻訳のレビューに参加した人が次は翻訳を手掛けているとかです。

そのうえで全体として以下の2つがどうバランスしているのかは、私にはわからないし、誰にもわからないんじゃないんですかねえ。

  1. 有名人は自分の利益のために業界や人々を利用している
  2. 有名人は業界や人々の利益のために自分の労力やお金を費やしている

全体として 評価するのが無理だという話であって、個別の具体的な場面や状況については、もちろん評価できるし対応もできます。著者もそういう具体的な経験を積み上げて本書を書いているはずです。いつ・だれが・どこで・どんなことをした、という話ですね。その中で問題だと感じたことを正直に、批判的に取り上げている。

ここに関して一点、著者に賛同できるところがあります。個別の具体的な場面や状況について批判的な意見を言ったり、全体にかかわる問題として取り上げるのが難しい、とりわけ有名人を批判するのが難しいという指摘です。その場で言っても流される、オープンな場で提起しても進展しない、自分が不利になりそうに感じるなどと著者は書いています。


さて、有名になるということについて、ここからは本書の内容を離れて、私個人が考えていることを書いていきます。有名になったのは運がよかったから、という考え方です。

これを「有名になったのは運がよかっただけ」と読み違えないでください。運だけと思うのは間違いです。有名になった人はそれだけの努力をしているし、貢献しているし、能力や実力も相応です。また有名になるための戦略的活動もしている人が多いでしょう。努力と能力と戦略だけでは、しかしながら、誰にでも同じ結果が出るのかというと、そうでもない、というかまったく違う結果にもなります。

私自身が界隈の有名人なのかどうか、しばらくコミュニティやイベントから遠ざかっていることもあり、どう判断されるかはわかりません。まあでも800人の中には入れるかな。そのくらい有名になるのに、運がどう関係していたか、私の経験を少しお話ししてみます。

私はアジャイルの初期から触れる機会に恵まれていました。まだ何も知らなかったとき、会社で人出し的にアサインされたのが、IBMと野村証券がXP (エクストリームプログラミング) を試みている案件でした。初期のイベントに参加しているとき「LTやってみない?」と声をかけてもらい、その場で初登壇することができました。大きかったのは『アジャイルな見積もりと計画づくり』の翻訳を角谷さんとしたことでしょう。15年たったいまでも読まれ続けている名著の翻訳に関われたのは、その話が出て「誰か翻訳する?」と聞かれたとき、たまたまそこにいたせいですし、他の人が忙しいか何かで手を挙げなかったせいです。

そもそも、ちょうどその頃にIT業界に若手として在籍していたのは昭和48年生まれ、小学生のころからパソコン (!) を触れる環境で育って、大学も情報系に進んでそのまま就職したせいですね。当時英語メーリングリストを読んでいて「あ、Light-weight Processって言われてたのがAgileに変わったんだ」というリアルタイムの記憶があるので、アジャイル25年やっている勢に分類されるわけです。

これを「運がよかった」と言わずしてなんでしょう。

いちおう、濡れ手で粟的なことだけでもないという、努力的な部分についても補足しておきます。

  • 小学4年生 (10歳) のときから中高大とプログラミングをずっとしていた。いわゆる青春とか記憶にない
  • プログラミングの勉強も書籍、英語メーリングリストなどでがんばっていた
  • 会社ではオブジェクト指向の社内勉強会を立ち上げたり、別のIBMの仕事で成果を上げたりした
  • XPやアジャイルを自社に導入しようといろいろ試した。怒られたり嫌われたりもしたが味方もいた
  • オブジェクト指向とアジャイルを専門的にやりたくて転職した
  • 翻訳もめっちゃがんばった。がんばって時間かけすぎて周囲の人や出版社にご迷惑をかけたりした

オ、オレけっこうがんばってたんだな。。。はらりはらり。。。というのは当事者たる自分の認識でして、「がんばったからできた」と思うのは当然だしそれ自体は正しいです。ただ、それだけではない、いろいろな運が働いたからこそ今の結果になっています。こういうことができる身体に生まれたところから始まり、東京に (そもそも日本に) 育つのは地球上ではSSR級のアタリですし、まあまあ氷河期だったのに就職できたこともそうなら、仲間同僚に恵まれたのも文字通り幸運でした。丸顔太っちょで優しい印象なのも有利な面がありますね。

自分は運がよかった、という認識はすなわち、そこまで運がよくない人もいた という気づきです。同じくらいがんばったのに、あるいは私よりずっとがんばったのに、結果では劣っている人がいる。数年遅れた人は黎明期の経験ができませんでした。住んでいるところにより機会はずいぶん違います。人生の中のタイミングもあり、家庭環境とか経済状況とかで、できることに大きな差があります (典型的には独身・結婚の時期、また子育てや介護ですかね)。上司ガチャなんて言葉もありました。

可能性として存在する、というだけでなく具体的、0/1という意味でも、特定の書籍を私が翻訳した結果、他の誰かが翻訳できませんでした。イベントの現地チケットが人気で即完売してしまうのをなんとか確保したとき、誰かひとり確保できなかった人がいました。私がリーダーになったプロジェクトは、別の人がリーダーならもっと良い成果を上げたかもしれませんが、その人には機会がありませんでした。限られた機会は、限られています。誰かが得たら誰かが失うゼロサムです。

有名になったのは運がよかったから。これは単なる事実です。資本主義的な思想なら、幸運というきわめてコスパの高いリソースを得て、正当に成功したという認識になるでしょう。運をつかむために努力したという言い分もあります。運も実力のうちというわけですね。

でも成功にも実力にも運が含まれているわけです。成功していない人、実力がない人は、そう見えているだけで単に運が悪いだけかもしれない。運というのは、同じことをしても結果が違うことを指すのだから、新しい機会があれば「運よく」高い実力を見せ成功するかもしれません。そう考えると、実績のない人にこそ機会を増やすのが公平なのではないかと思えてきます。そのほうがコミュニティ全体、界隈全体の成果やメリットを増加できる、という計算が成り立ちます。

ここであらためて本書に戻ってみると、著者の主張では有名人に機会が集中しすぎるということでした。私はその主張に対して、個別の事象としてそういうことはあるが、逆に機会を分散する仕組みもあり、全体のバランスはわからないという考えを述べました。また本記事の後半では、有名人は運がよかったという観点を提示し、ここからも機会は公平であるほうがよいという結論になりました。

どうでしょうね。こうまとめると、つまり機会は公平にあるほうがいいよねと言うと、あたりまえに聞こえます。著者の主張も、あたりまえということに、なるでしょうか。そうでもないでしょうか。そのうえで、著者が指摘するような問題点、機会の集中とそれによる弊害が実在するのなら、それは直したほうがいいよねと思えるでしょうか。

私はそう思います。運がよかった人とそうでもなかった人が、格差で分断されるのではなく、お互いに敬意をもって支えあえるほうがいいです。役割分担をするなら、これまでやってきたことではなく、これからできることで分けたいです。

さて、著者がどんな弊害を指摘しているのか、これを見ていくと問題が具体的に識別できるかなと思うのですが、今回はあいかわらず長くなってしまったので、それはまた次回。。。というものが来るのなら、書ければ次回取り上げようと思います。

『アジャイルを飯の種にして生きる人々』感想文 その1・有名さが先走る話

『アジャイルを飯の種にして生きる人々』(匿名アジャイルプラクティショナー 著)について書きます。

長いので最初に、生成AIによる要約です。この要約を除き、記事作成に生成AIは用いていません。

実力ではなく「先駆者・有名人」という肩書だけで高額なコーチが採用され、現場で成果を出せないという本書の提起に対し、筆者もこのミスマッチが業界に広く実在し、アジャイル普及の悪影響になると結論づけています。 (Gemini)

SNSを見ていると、みょうにこの本に批判的、というか取るに足らない、くだらないという評が目立つように感じたのですが、私としてはそんなことはない、現実に存在する影響のある問題について実質的な提起をしていると思いました。怪文書よばわりするのはもったいないし、そもそも匿名の著者にリスペクトを欠く振る舞いでもあります。まあ「取るに足りない」「自分には関係ない」「もっと重要なことがある」という反応は、アジャイル導入なんかでも、本当に行動を変えてほしい人からよく受けるものでもありますね。聞いてほしい人は聞く耳を持たないがちです。

とはいえ真剣に読もうとすると、著者にはすみませんがたいへん読みにくい。表現が大仰だしおんなじ話や表現が何度も何度も出てくるし主旨がなかなかつかめない。また具体的人物や事例に触れないようにされているので、曖昧だったり主語大きすぎにもなりがちに感じます。本にするだけの内容があったのかは、なんとも言えないかも。話題になったという点で、Amazon PODやKindleにした作戦勝ちというところなのかな。

そういうわけで私も熟読してるかというとそうでもないです。すみません。また著者の主張 (だと読み取った内容) に全面的賛成でもありません。なので、書評というよりは感想文という位置づけで、読んだうえで私自身が考えたことについて、ここでは書いていきます。

目次を見ながら読んでいると、構成はよく練られていて、指摘すべきポイントを整理して押さえていると感じました。とはいえ全11章の配分もすでにちょっと細かすぎて、論点は5個くらいに絞れるのかなあ。中心にあるのが「先駆者という立場の人たち」についてです。

先駆者とは、アジャイル黎明期からやっていたり、海外の有名人と交流があったり、コミュニティ発足メンバーだったり、講演や著書がたくさんあったりする人だと思います。いろいろな表現がされていてかえってイメージがぼけているのですが、まあ有名人というところなのかなあ。有名人は活動や実績、貢献を積み重ねて有名になるのですが、有名なので次の仕事や講演の機会も多く得られます。お金もたくさん稼げるでしょう (たぶんね)。

本書の指摘の一つに、そうした有名人が能力や功績ではなく「有名である」ということで特別な地位や扱いを受けており、そのためにアジャイル導入をしたい会社や現場が不当に不利益を受けている。要は導入に失敗している、というものがあります。 私はそのように読み取りました。

本書の第3章「アジャイルで飯を食う方法(1): コンサル・コーチ」では、会社や組織へのアジャイル導入について詳しく書いてあり、スクラムマスターやアジャイルコーチがどんなことをするのか、また対象・規模・文化などでどんな問題が起こりうるのか挙げられており、よく書けていると思いました。偉そうに言うなや。また失敗パターンも整理されていて、特に外部のチェンジエージェントが陥りがちな状況も紹介しています。

アジャイル導入というのはよく失敗してきました。そもそも導入したい人がアジャイルを理解しなかったり、成功条件を定めなかったりもしがちですし、パイロットで成功しても全社導入せずに終わったり、関係者の意思・意図がそろわずに難航するのもあるあるです。著者もよく理解されているようです。そこでスクラムマスターやアジャイルコーチ、外部のチェンジエージェントを参画させ成功確率を上げようとします。

しかし誰に頼めばいいのか? エンジニアやPMなら評価もできるけど、SM・アジャイルコーチってなにそれ? なにしてくれるかもよくわからないし、有能なのかもよくわからない。特にスポンサーはアジャイルの前提知識もコミュニティのことも知らないので、判断のしようがない。仕方なく、有名な人とか単価の高い人なら、きっと優れているんじゃないかという判断になりやすい。ある人の前評判が、能力や実力とあまり関係なくなってしまう方向にフォースが働く。そういう採用判断の話に加えて実際の活動でも、優秀な人、本当にマッチした人でもどうしようもない状況というのもあって、依頼側にも参画側にも不満が残りやすい。守秘義務も関係して、ある人の本当の実績というのは不透明になりやすい。

これを僻目で眺めれば「有名ってだけロクな仕事しないで金だけとるやつ」が出てくる、増えてくる、けっこう多いというふうに見えます。ここで紹介しているのはそういう指摘です。

さて、この指摘に関して、「有名人ってどのくらいの有名さよ」という疑問が混乱を起こしやすいです。というか私は混乱しました。本書の読みにくさもあり、誰に対して指摘しているの? というところがわかりにくいんですよね。本書では何度か以下のような記述があります。

フリーランスSMの月額相場は80万〜120万円と、一般的なエンジニアの給与水準を大きく上回ることが珍しくない。 (Kindle位置1014)

フリーランスSMで月額80万〜120万円、大手コンサル経由なら月額100万円超も珍しくない。1回のセミナー講演で数十万円以上のギャラが発生する場合もある。(Kindle位置1226)

「3.2 「スクラムマスター」「アジャイルコーチ」の肩書と職能」の中の文章なので、アジャイルコーチも近い金額という想定だと思われます。また別の個所ではSMは週数回ペースでと書かれているので、いわゆる1.0人月の金額ではなさそうです。あと売り上げと給与を比較してるあたりは、意図的なのか知らないのかわかりませんが、やっちゃいけないやつですね (Geminiどんに聞きましたが、フリーランス月100万売り上げはサラリーマンの給与額面67~75万に相当)。

本書で想定している有名というのは「名前だけでこの金額が取れるくらい」の有名さと考えると良さそうです。それってどれくらい? と言われるとうーむそれはそれでわからん、となるのですが、なんというか、超有名人、業界を長年けん引してきた先駆者、トップオブザトップ、アジャイル界隈で知名度の高いベスト30みたいなイメージよりは、だいぶ範囲が広い気がします。めっちゃ乱暴に言うと、800人くらい? そこまで先駆者って呼んじゃう?

さて、あらためてこの指摘についてまとめると、

  • アジャイルの普及活動やコミュニティ活動で名前を売っている人が
  • 実際の現場では大して成果を出せない (こともある)
  • それは普及発展を阻害しコミュニティに悪影響がある

つまり仕事の (現場での) 能力とは必ずしも関係ない「有名人」というラベルのせいで、現場で成果を出せないスクラムマスターやアジャイルコーチが発生しているということだと理解しました。そしてこれは業界全体で数名とか数十名との有名人ではなく、もっとずっと幅広い、人数として多いところで起きている話であると。

うん、きっとそうでしょうね。一定の割合で、実際に起きていると思います。会社として当たり前に考えれば、仕事の能力が高い人に仕事をしてほしいです。それが、そうなっていない。有名な人だからと依頼したら、期待ほどではなかったと。もちろん責任がどっちにあるかは、ケースバイケースですし、個々の状況はそれぞれに対応し解釈していただくしかない。とはいえ「やっぱりアジャイルはダメなんだ」と思う人や会社が増えるのはアジャイルの実践者としてもコミュニティとして嬉しくはありません (あまり関係ないという立場はあると思う)。私としては、現場での実績がもっと透明になって、依頼側も自分の状況で本当に役に立ってもらえそうな人を選べる仕組みが整うといいなあと思います。

そして数多くある論点の1つだけで死ぬほど長くなってしまいました。続きます。ほんとかな。

生成AIを利用した開発の最近の自分のようす

開発というともっぱら個人開発をしており、そこで生成AIを使っていますが、最近の自分自身の使い方やツール選び、ワークフローと言うと大袈裟な感じがしますがそういう進め方について、メモしておこうと思います。2025年11月~2026年2月くらい時点のはなしです。

メモなのでたいへんに長くなりました。こちらは Gemini どんによる簡単なまとめです。生成AIを「~どん」と呼ぶのも最近のようすです (読みにくくなるので文中では呼び捨て)。

この記事は、個人開発における生成AI(主にClaude CodeやGemini)の活用手法について、2025年11月から2026年2月時点の状況を記録したものです。コーディング、テスト、設計、レビューなど多岐にわたるタスクをAIに依頼する際の「コンテキストの構築方法」や、作業内容に応じた「委託と伴走の使い分け」について、実際のプロジェクトの事例を交えて解説しています。

また文末に書いたまとめを、ここにも載せておきます。

生成AIにやってもらうこと

  • コーディング・実装
    • 仕様を実装、テストしてもらう
    • UI修正、見た目の調整
    • Issueへの対応とPull Requestの作成
    • 曳光弾開発をお任せ。AWS Amplify、CDK、外部サービスへの接続など一気に
  • テスト・環境構築
    • テスト駆動開発をする
    • ユニットテストを書く、書けるようにリファクタリングする
    • ユースケースシナリオを元に Playwright でE2Eテストを書く
    • E2Eテスト用の実行環境を作る。LocalStack、Dockerコンテナなど
  • 設計・要件定義
    • 設計の選択肢を作ってもらう。モジュール構成、サービス選定、テーブル設計など
    • 選択肢を比較評価するための観点出しと、評価のサポート
    • アーキテクチャを検討し、ADR (Architecture Decision Record) に書き残してもらう
    • ユースケースシナリオのバリエーションの追加
    • セキュリティ上確認すべき項目の整理
  • レビュー・ドキュメント作成
    • Pull Requestや実装したコードのレビュー
    • 人間の「仕様の理解」や「相談した内容の認識」のレビュー
    • 仕様変更や設計追加に伴うドキュメントの更新・同期
    • 長くなったチャットの議論を残す (Issue、ADR、仕様書など)
    • スキルやサブエージェント作成
  • 相談相手、頼れる先輩
    • 仕様の判断や、見落とし・落とし穴の検証
    • 既存コードの説明や、サンプルコードを作る
    • 一般的な知識の把握や、よくわからない技術の解説
    • 相談途中で論点を整理する。まだわからないこと、判断ポイントなど
    • 作業の進め方の相談相手と、TODOリストの作成

生成AIの参加スタイル:

  1. 自分 (人間) ができる、完成形を100%想像できること → 一発でやってもらう
  2. 情報や検討が必要、わからない点があること → 選択肢を作ってもらう
  3. それ以外 (何がわからないかわからない、など) → 伴走してもらって相談する

さらに NotebookLM によるまとめも作ってみました。一般向けに共有していますが、NotebookLM 自体にログインしないと見られないようです。

文中で例として示しているのは以下の、私の個人プロジェクトのコードや作業の様子です。

なお記事本文には生成AIの書いたテキストは利用していません。箇条書きのまとめは生成AIに書いてもらったものを手直ししました。NotebookLM によるまとめは生成AIによるものです。

Claude Code中心

コードを書くことや、それだけでなく設計の相談やレビューは Claude Code が中心です。普通のチャットは Gemini も常用していて、一般的な議論や知識の把握にはこちらを使うことも多いです。

自分のルール設定

AGENTS.md に自分とのコミュニケーションで大事なことと、開発中も常に意識してほしいこと (シンプル重視など) をごく短く書いています。CLAUDE.md には AGENTS.md を見る指示だけ書いて、AGENTS.md に自分のルールを書いていますが、これはほかの CLI も試していた関係で、Claude だけだったら不要でしょう。Copilot も見てくれると思います。

CLAUDE.md:
# Guideline for Claude Code

You must read @AGENTS.md first before reply anything.
AGENTS.md:
# Chat with user

- Use Japanese language even if the user provides English input.
- Refer to the user as やっとむ.
- Reply in a clean, unambiguous, friendly but not too-casual, to-the-point and yet kind manner.  Use 常態 not 敬体.
- Ask a lot of questions to understand user's intent correctly.  Do not guess.
...

AGENTS.md を読んだ Claude Code

AGENTS.md に自分とのコミュニケーションで大事なことと、開発中も常に意識してほしいこと (シンプル重視など) をごく短く書いています

プロジェクトの情報は README.md に書いています。プロダクトの内容、利用するコマンド、前提条件などです。人間に見てもらうつもりで書いていますが、生成AIも参照してくれるようです。

スキルとサブエージェント

Claude Code にはスキルという機能があって、独立したひとまとめの知識を別途ロードできるように書いておけます。現在はそんなに活用しておらず、テスト駆動開発 (TDD) のスキル、git コミットコメントのスキル、ADRの書き方のスキルを使っています。スキル自体は生成AIに手伝って書いてもらいましたが、生成AIが書いたスキルはあまり有用ではないという研究もあるようです。また数日前にAnthropic公式のスキル作成スキルが更新されたという話も見かけました。

またプロジェクト独自のビルドチェーンやコマンドの使い方も、スキルに書いています。

サブエージェントはスキルに似ていますが、スキルは知識としてロードされるのに対し、サブエージェントは新しいエージェントを起動して作業を委譲する仕組みです。仕事に必要な知識とコンテキストだけを使うので、全体のトークン消費をおさえられるそうです。こちらもあまり使っておらず、コードレビューのサブエージェントを作って使っています。

一般的な知識でも、プロジェクト固有の知識でも、人間と共有すると役立つようなことは生成AIと共有しても役立つと思うので、スキルなどで明示しています。またこれはリポジトリで管理します。複数のプロジェクト、複数のプロジェクトで重複して管理することになるのが気になりますが、今はうまいやり方がわかっていません。適宜コピーしています。

スキルなどはプロジェクト横断 (ホームディレクトリ) とプロジェクト固有 (プロジェクトのディレクトリ) に置けるので、共通のものはホームに置いてもいいようです。

一般的な知識でも、プロジェクト固有の知識でも、人間と共有すると役立つようなことは生成AIと共有しても役立つと思うので、スキルなどで明示しています

またプロジェクト独自のビルドチェーンやコマンドの使い方も、スキルに書いています。

すべてはコンテキスト

生成AIに作業を依頼するときには、依頼するときに渡す情報=コンテキストがたいへん重要です。プロンプトもコンテキストの一部ですが、読んでほしいファイルやドキュメント、参照してほしい情報も重要なコンテキストです。またチャット上でのこれまでのやり取り全体もコンテキストです。

ひとつのまとまった作業を依頼するとき、その作業に関連する情報をチャットのやり取りで渡したり、相談しながら詳細を決めたりして、作業に有用なコンテキストを積み上げます。話が長くなるときは、いったんそこまでの話をドキュメントとしてファイルに書き出してもらい、必要に応じて人間が手直しして、それをあらためてコンテキストに含めるということもします。既存のAPIを使うときは、そのAPIの仕様や使い方の説明ドキュメントなどを的確に渡すことも意識します。

ひとつのまとまった作業を依頼するとき、その作業に関連する情報をチャットのやり取りで渡したり、相談しながら詳細を決めたりして、作業に有用なコンテキストを積み上げます。

Claude Code には plan mode があります。コードやドキュメントの修正のような、既存の内容をいったん把握するのが大事なときは、plan mode に切り替えて必要な情報を収集して作業専用のコンテキストを作ってくれます。また、テスト駆動開発のスキルでは docs/plan.md に詳細な手順 (テストリスト) を書いてから進めるように指示してあり、このスキルで仕事を進めてもらうと同じように的確なコンテキストを作ってくれます。plan mode の内容は直接編集できないので、 人間もさわれるファイルに書いてもらう方が便利かもしれません。

GitHub 上の Copilot と Claude Code

GitHub には Copilot がいろいろと組み込まれているので、適時使っています。 今のところは PR に対して Copilot にレビューしてもらうというのがもっぱらです。 特にプロンプトを書かずにレビューしてもらっているので、精度はほどほどですが、あからさまな問題を見つけてくれることがあるので、採用しています。 実装も頼めますが、なんとなく Claude Code のほうを信頼しています。

また GitHub リポジトリに Claude Code を呼んで設計や実装、レビューもしてもらえます。デフォルトだとすべての Pull Requests に Claude Code のレビューが走り、なによりトークン消費が激しいので、明示してコメントで呼び出したときだけ実行するように修正しています。

.github/workflows /claude-code-review.yml の修正箇所

Issue や Pull Request のコメントで @claude を呼び出すと、作業を依頼できます。Issue の場合は、作業が終わったあとで「Create PR」をクリックして対応する Pull Request を作成します。

Claude Code に Issue に対応してもらう

なんでも生成AIを使うが、委託と伴走を使い分ける

さて、ある意味本題の、生成AIになにをしてもらうかの話です。基本的にはなんでもやってもらう、というか参加してもらいますが、参加のスタイルがいろいろあります。自分でもあまり整理できていないのですが、いくつかのルールという形で意識していることがあります。

まず簡単なのが、小規模な作業で、自分で作業したらほぼ悩まずに終わる、最初から完成系のイメージがだいたいわかっている場合です。ロジックのバリエーション追加、項目の変更、見た目の調整など。つまり、自分でできる、自分にとって簡単な作業。これは一発のプロンプトで指示をして、完成したら軽く確認する。典型的な委託作業です。特に渡すコンテキストを調整する必要もありません。テストも書いてもらうので、テストコードを見れば結果は大体把握できます。

こうした一発の作業は、どんどん Issue に書いていってつぎつぎに並列で進めてもらいます。並列しすぎるとマージで手間取ることはあるので、そこはほどほどに。10分とかで終わるので、そんなに同時並列することもないと思っています。ところで複数の PR のマージもまとめて依頼できそうな気がしますが、自分で結果確認するタイミングが入るので、いまのところ全部任せにはしていません。してみてもいい気はします。

自分でできる、自分にとって簡単な作業。これは一発のプロンプトで指示をして、完成したら軽く確認する。典型的な委託作業です。

正解を求めない その1・選択肢を作ってもらう

自分で作業するとしたら、あるていど考えたり調べたり、試行錯誤したりする仕事があります。だいたい見当はついているけれど、わからないところもある。こうすればできるかもしれないし、あっちのほうがいいかもしれない。そうした仕事を生成AIにそのまま依頼すると、なにがしかの判断が裏で行われることになります。その判断は正しいかもしれないが、間違っているかもしれない。また正しいとしても、人間のほうが正しいかどうか判断できないかもしれません。

そんなときには生成AIに選択肢を作ってもらいます。こうして単に仕事を進めるだけでなく、人間が仕事の進行についていけるようにします。生成AIの成果をどれだけ人間が把握しておく必要があるかは、よくわかりません。私は自分がわかっておきたいと思ったときには選択肢を作ってもらい、自分で比較評価し、比較評価自体も生成AIと相談したり観点を補ってもらったりしつつ、自分の判断として方針を決めます。選択肢を見ていると、もっと良いアイデアが出てくることもよくあります。このへんの話は2025年の講演スライドにまとめたので、そちらも参考にしてください。

自分で作業するとしたら、あるていど考えたり調べたり、試行錯誤したりする仕事があります。そんなときには生成AIに選択肢を作ってもらいます。明示的に「いくつか選択肢を出してください」と頼みます。

www.docswell.com

選択肢がほしくなるのは、主に仕様あるいはやりたいことが決まっていて、その実現方法が固まっていない場合です。いわゆる「設計」をこれからするぞ、というときですね。ロジックやアルゴリズムについての選択肢もあれば、モジュール構成の選択肢、採用するサービス選定の選択肢、テーブル設計の選択肢など様々です。

選択肢を作るのに git worktree が便利

選択肢を作るには、普通にプロンプトで明示的に「いくつか選択肢を出してください」と頼みます。ただしこれはアイデアとか、設計の概要・方針とか、短いコード部分などに限られます。

まとまった量のコードについて、複数の選択肢を実装して見比べるのには git worktree を使います。git worktree は別々のディレクトリに別々のブランチをチェックアウトする機能です。これを使うと、並行して複数の実装をそれぞれのブランチで進めて、結果を見比べられるようになります。画面を見るとイメージが分かると思います。 git worktreeを使ったときの簡単なイメージの動画を作りました。後半の1:26から見てみてください。

Claude Code などの CLI で git worktree を使うのは一般的なので、検索すればやり方はすぐ見つかります。私は branches/wt1 などのディレクトリを、必要に応じて作ったり終わったら消したりしています。作ったときには pnpm install や .env ファイルの配置などが必要になるので、頻繁にやるならなにかサポートが欲しいところです。世の中にすでにありそう。docker compose も各 worktree 内で独立して動かせるので便利です。VSCode も git worktree に対応しているそうです。

選択肢を作ってもらうのは、アイデア出しを生成AIに委託し、すこし伴走してもらったうえで、自分の判断を元に残りを委託するという参加スタイルになります。

私は自分がわかっておきたいと思ったときには選択肢を作ってもらい、自分で比較評価し、比較評価自体も生成AIと相談したり観点を補ってもらったりしつつ、自分の判断として方針を決めます。選択肢を見ていると、もっと良いアイデアが出てくることもよくあります。

正解を求めない その2・相談しながら

選択肢を作ってもらうのも難しいときがあります。そもそもなにをしたらいいんだっけ、実現方法がさっぱり思いつかない、頭の中がいろいろもやもやしている、そんなときです。こんなときは生成AIにべったり伴走してもらい、チャットで相談しながら進めます。頭の中で整理すればできるんだけど、面倒くさい、おっくうだ…というエネルギー切れのときも、相談ならぼちぼち進める感じがします。

相談する項目は様々です。仕様の判断、見落としや落とし穴の検証、設計の方針、どのサービスやAPIを使ってどう実現するか、コードを説明してもらって理解する、コード例を出してもらう、テスト内容を考える。単に良くわからないことを教えてもらうのもいいですね。一般的な知識、情報も相談できますが、ドキュメントやコードを踏まえた質問もできます (これはコンテキストを整えることを意識するとよい。このドキュメントを見て、このコードを読んでから答えて、など)。

相談を始めるときは、チャットのセッションを初期化してコンテキストを空にしましょう。Claude Code なら /new コマンドでリセットできます (ちなみに以前のセッションには /resume で戻れるので、一時的に相談するのも大丈夫)。最初のひとことで最初に相談したいテーマを提示すると、あとで /resume するとき見分けやすいので便利ですし、そのほうが反応も的確になる気がします (LLMはプロンプトの最初と最後が重視されると言いますが、ここでも関係あるのかな? あんまりない気はしています)。セッションをリセットするとトークン消費も減らせるので、その点でも意識するといいですね。

そもそもなにをしたらいいんだっけ、実現方法がさっぱり思いつかない、頭の中がいろいろもやもやしている、そんなときです。こんなときは生成AIにべったり伴走してもらい、チャットで相談しながら進めます。

相談のしかた

相談するときはオープンクエスチョンを意識します。相談しているのは、自分でもよくわからないからなので、よくわかっていない自分が主導・誘導しないよう、生成AIにいろいろな情報、観点、見方をしてほしいわけです。

  • クローズドクエスチョン: YES/NOで答えられる質問 「〇〇でいいですか?」「問題ありますか?」「他にありますか」
  • オープンクエスチョン: 回答が無数にありえる質問 「〇〇はどうですか?」「気になる点を教えて」「他のアイデアを出してください」

自分が理解した内容を文章で説明して、それをレビューしてもらうのも有効です。生成AIに教わった内容を理解できているか、相談してきた内容について認識が合っているか、見落としや考え違いがないかなどが確認できます。生成AIにまとめてもらって終わりだと、あとで勘違いに気づくことがよくあります。

あるていど相談が進んだところで、論点をリストアップすることがあります。相談前にはよくわかっていなかったことが、徐々にわかってきます。わかってきたところで、わかったところ・まだわからないところ、判断が必要だとわかったポイント、新たな疑問点などを、途中で一覧にします。これがすべて解決したら相談は終わり、作業を進められるという判断ポイントが作れます。なんとなくわかった、納得したという感覚でなく、なにが解決したからOKなんだと明示できます。こういう話をしたときは、だいたい結論を Issue に書き残してもらうことが多いです。

相談はチャットだけで完結せず、コードやドキュメントなどを更新しながらできます。コードを少し書いてもらった上で質問するとか、話した内容をドキュメントに反映してもらいつつ関係する情報を整理してもらうとか、TODOリストを書き出してもらうとか。TDDのピンポン (人間と生成AIが交互にコードとテストを書くこと) もこの進め方の一種かもしれません。

ドキュメントの更新は忘れがち

細かい点でも仕様が変わった場合や、設計に追加変更があったときは、ドキュメントも更新する必要があります。生成AIのおかげでコードとドキュメントの同期はたいへん楽になりました。ですが生成AIのほうも調子に乗って開発していると、ドキュメントを忘れることがよくあります。人間が忘れないように意識して、ときどき確認したり、明示的に指示しています。このへんは AGENTS.md やスキルなどでワークフローをしっかり定義してあげると、意識しなくてよくなるかもしれません。まだ試したことはありません。

生成AIのほうも調子に乗って開発していると、ドキュメントを忘れることがよくあります。人間が忘れないように意識して、ときどき確認したり、明示的に指示しています。

テストはガードレールであり案内標識である

生成AIを使わなくても、現代のソフトウェア開発でテスト自動化は欠かせません。生成AIを利用するときには、自動テストの存在がさらに価値が増しています。生成AIがコードの振る舞いを意図せず変えてまうことがありますが、自動テストがあれば振る舞いの変化にすぐ気がつけます。またそもそも生成AIが正しいコードを書いているか、人間がコードを見て確認するよりも、どう動作するかを確認する方が確実ですし、時間もかかりません。プロダクトコードをすべてレビューして問題がないか探すのであれば、自動テストを書いて、そのテストの挙動を確認しましょう。多少のミスがあっても事故につながるのを防ぐ、ガードレールの役割です。

私が生成AIにテスト駆動開発を指示するようになったのは意外と最近で、2025年まではあんまりテストを書かずに進めてしまうことが多かったです。反省としては、ちゃんとTDDするときは伴走する必要があるという気がしていて、委託するときはテストは手を抜いていました。2026年からは委託するときも基本的にTDDで進めるよう AGENTS.md に記述し、そのためのスキルも設定しました。人間と生成AIがピンポンするTDDも有意義ですが、生成AI単独で進めるときもTDDが有効だと理解したのは比較的最近、というわけでした。

生成AIを利用するときには、自動テストの存在がさらに価値が増しています。生成AIがコードの振る舞いを意図せず変えてまうことがありますが、自動テストがあれば振る舞いの変化にすぐ気がつけます。

TDDのスキルの中に、ユニットテストでは外部依存を用いず、モックもできるだけ避けて、ロジックだけを抜き出してテストできるように設計する指示を入れています。これは私の志向が強く出ていますが、ユニットテストでのコードカバレッジはあまり高くせず、アプリとしての仕様を直接表現できるテストを重視しています。

.claude/skills/test-driven-development/SKILL.md (抜粋):

# Tests

- Write unit tests for TDD.
- Avoid using mocks as much as possible.
- Readability is more important in test code so avoid dependencies and over reuse and make every single test cases easy to understand just by themselves.
- Order test files and test cases so that the organized tests represents the structure of the specification.
- Make sure that unit tests does not use actual external resources like DynamoDB and also does not use mocks.  The very interface with external resources should not be tested in unit tests.  When we want to test logic we wrote, refactor them out into a separate method/function/class/module and then write unit test for them.

E2E テストは Playwright

アプリとしての動作を担保するテストは Playwright のテストを書いてもらっています。まずは仕様をまずユースケース記述やシナリオとして書いておいて、それを自動化してもらいます。ユースケースシナリオのバリエーションは生成AIに増やしてもらってもいいですね。部分的には、機能単体を確認する E2E テストもありますが、あまり増えすぎないよう気をつけています。

E2E テストは実行環境を作って維持するのが手間ですが、ここは生成AIに全面的に頼りました。もろもろのAWSサービスを LocalStack で構築し、フロントエンドもテスト実行もそれぞれコンテナにして、docker compose run でテストを実行するようにしています (説明なしでコードをシェアしても、生成AIに聞けばすぐ解説してもらえるので、シェアも気軽にできていいですね)。テスト結果はホストディレクトリをマウントしてそこに出力しています。

仕様をまずユースケース記述やシナリオとして書いておいて、それを自動化してもらいます。機能単体を確認する E2E テストもありますが、あまり増えすぎないよう気をつけています。

E2E テストを BDD や ATDD のテストと位置づけて、先にテストを書くやり方も可能だとは思いますが、実践はしていません。自分で仕様を考えて自分で作る個人開発だと、あまりメリットを感じません。生成AI向けには、ユースケースシナリオが目標としてのテストの位置づけになるように感じています。

ドキュメント上で進め方の方針を共有

plan mode を使えば、まず進め方の方針をまとめて、確認もできます。ただしいったん作業が始まると介入しにくくなります。TDDをするときには、生成AIと人間が双方でさわれるところに進め方を書いてもらっています。スキルで明示して、 docs/plan.md の中にTODOリストを書いた上で進めるよう指示しています。

docs/plan.md (抜粋):
# TODOリスト

NOTICE: TODOリストはフラットな箇条書きで、着手順に上から並べること。新しい項目もフラットに、実施順になるよう途中に挿入する。セクションを分けたり階層化するのは禁止。

- [x] README.md作成
- [x] docs/spec.md作成
...
- [x] EthicsMap: N2ノードにポイントを割り振れる (上限は親N1のポイント)
- [x] EthicsMap: ポイントを増やすとPのポイントが減り、減らすと戻る
- [x] EthicsMap: Pのポイントが0のとき他のノードのポイントを増やせない
- [x] EthicsMap: 子ノードのポイントを超える親の減少はできない
...
- [ ] ollamaClient モジュールを実装する (src/services/ollamaClient.js: 接続確認・ テキスト生成)
- [ ] F09 OllamaStatus コンポーネントを実装する (接続インジケーター)
- [ ] F08 EthicsCodeView コンポーネントを実装する (倫理綱領テキスト表示・ローディ ング)
- [ ] F08 ポイント変更時のリアルタイム生成を App.vue に組み込む (debounce付き)

実際のところはすべての開発作業をここに書きながら進めているわけではないようです。人間が忘れる場合もあり、Claude Code も忘れていたりしますが、細かい作業は GitHub Issue に残っているのでわりと関係ないです。大きな作業を計画するときには、確実にここで計画、方針を検討するようにしています。人間が見直したり、部分的に伴走に切り替えたり委託に戻したりもやりやすいです。

TODOリストはTDDのテストリストの位置づけと同じで、自分がどこに到達しようとしているのか、そのためどうやって進むのか、案内標識や目印やリマインダーとなります。同時に、自分が設計をどのように理解しているのかのバロメーターともなり、理解が中途半端なまま進もうとしたときの黄色信号の役にも立ちます。自分でテストリストを書けなかったり、テストリストの項目が理解できなかったりしたら、立ち止まる合図です。生成AIに委託しているなら、一時的にでも伴走で進めるタイミングです。

自分がどこに到達しようとしているのか、そのためどうやって進むのか、案内標識や目印やリマインダーとなります。同時に、自分が設計をどのように理解しているのかのバロメーターともなり、理解が中途半端なまま進もうとしたときの黄色信号の役にも立ちます。

Claude Code の plan mode ではファイルを更新できず、ドキュメントも書けないので、docs/plan.md にTODOリストを書くときは編集可能なモードでやってもらいます。

CLIがいちばん快適

Claude Code だけでなく、作業はWSLのシェル (Windowsターミナル) で、tmuxでウインドウやペインを分割しています。 基本構成は、Claude Code を左ペインに、右ペインは普通のシェル作業や一時的に vim を開くところ、なにか実行するときは右上に小さく開いておくかたちで、最近は安定しています。

エディタが必要なときはvimを使います (長年のvimmerですが、特に使いこなしてはいません)。 以前はIDEをメインで使っていましたし、今でも使いますが、そもそもエディタを使う場面がずいぶん減ってしまいました。 複数のファイルをエディタで眺めるときは別ウインドウで開きます。

Claude Codeがいるtmuxのメインウインドウ

正確で高速なシェル操作

シェルとCLIがいちばん反応が良く、若干非力ないまのノートPCでも快適に動きます。VSCodeやIntelliJ IDEAも使うことがありますが、開発環境がWSLだったりDockerだったりで重くなってあまり気持ちよくないです (これは環境への投資の話でもある。新PCをセットアップ中なので、今後変わるかもしれない)。

npm (pnpm) や uv、またAWS CLIなどのコマンドを繰り返し正確に実行できるのもCLIの大きなメリットです。良く使うコマンドはシェルのエイリアスや git alias を設定し、またほとんどのコマンドはシェルのヒストリから実行します。またプロジェクト独自のコマンドは、pnpm run に仕込んでいましたが見通しが悪く把握できなくなってきたので、Python Invoke に移行しようとしています。

Claude Code の操作

英語キーボードで日本語IMEのキーバインドをカスタマイズしていますが、日英の切り替えがどうも煩雑に感じるため、Claude Code への指示は主に英語でしています。ややこしくて上手に書けないときは日本語で。英語で入力する方がトークン消費も少ないんじゃないかな。たぶん。

利用プランと利用量

Claude CodeのプランはProなので、まとまった作業をしているとすぐ使い切ってしまい、数時間待つことになります。業務でフルタイム開発しているなら困りますが、自分の場合・現状の範囲ではひと区切りつけられるので、まあいっかという感じです。ときどきはチャージしてある金額で追加の作業をしますが、何十ドルも一気に溶かすようなことはしていません。

Googleにも課金しているので、普通のチャットはGeminiを使っています。アーキテクチャやインフラ、設計の一般論についてはGeminiで基本を把握することも多いです。Gemini CLI も以前に試したのですが、なんとなく使っていません (理由を忘れた)。

ゼロから始めるとき

新しいソフトウェアをゼロから書き始めるということは、今まではあまりなかったと思うのですが、生成AIがある意味いちばん生きるところでもあるので、一気に増えてきている気がします。私がゼロからスタートするときは、こんな流れになっているようです。

  1. やりたいことを書き出す
    • ユーザー視点から、やりたいことを書き出す。文章でも箇条書きでもいい
    • ユースケース記述やシナリオを書く (docs/spec.md)
    • 画面の構成やデザインに注文があるなら書く。文章でも、手描きでも、Figmaでもいい
    • 利用者視点から、技術要件やアーキテクチャ要求があるときには、書き出す
      • 例: AWSを使う、静的Webアプリ、将来〇〇もサポートしたい、など
    • ここでは生成AIチャットで壁打ちしたり、アイデアを出してもらったり、全体をレビューしてもらったりします
  2. アーキテクチャを検討する
    • やりたいことを実現するのに必要な技術要素、スタック、利用サービスを整理する
    • この時点では確定せず、候補や選択肢を複数出してキープしておく
    • アーキテクチャ要求の単位でADRを書く。たいていは TBD や porposal の状態になる (docs/adr/ADR*.md)
    • ここでは生成AIにもりもり考えて、書いてもらいます。選択肢を出してもらい、さらに選択肢の評価観点も出してもらい、そのうえで選択肢を評価してもらいます。チャットで壁打ちする部分もあるし、まるっと任せる部分もあります
  3. 曳光弾開発をする
    • やりたいことから主要な要素を選び、さらにアーキテクチャの主要な要素をすべて利用する組み合わせを選ぶ。そのうえで生成AIに実装してもらう
      • ややこしく聞こえますが、要はやりたいことの技術的な実現性を確認します
    • ユーザーに見せるものではないので、機能的にも見た目的にも最小限で
    • セキュリティ上確認すべき項目も、ここで整理する
    • 自分が知らないことを確認する部分なので、生成AIに大いに委託します。できあがったものを人間が理解するためチャットなどで質問したり整理してもらったりします。実現性を確認すべきポイントについても、丁寧に相談しながら網羅します。動くのがゴールではなく、人間が理解して納得するのがゴールです
  4. ユーザーに見せられる最小限の機能を作る
    • ユーザーフィードバックを得られる最初のリリースを作る
      • どんなユーザーにどうフィードバックをもらうかで、「最小限」の量は大きく変わります
      • 仲間内でアイデアを確認するレベルなら数時間~数日、ユーザー候補に実用してもらうなら数週間になることも
      • どの機能を最初にリリースすべきかは、生成AIと相談できます
    • ここまで来ると、進め方としては普通に機能を作り足していくだけ
    • この段階では自動テストを必ず作成する
    • 生成AIにコードを書いてもらい、テストを書いてもらい、ドキュメントを更新してもらい、レビューしてもらい、Issue と PR を書いてもらいます。上で説明した、小さいから委託する /選択肢を作ってもらう / 相談しながら伴走する のモードを切り替えながら進めます

やりたいことの書き出しとアーキテクチャの検討まで進めたときの例がこちらです。

github.com

また、こちらはやりたいことをしっかり目に書いた例。

github.com

このときは、やりたいこと (プログラマーの倫理モデルを考案する) を決めるために Gemini と1週間ほど相談しました。それが決まったところからは、ユーザーに見せられるところまで、5時間くらいで進めました。

最初の1日で進めた内容

生成AIでなにが高速化するのか

これはとっても感覚的・個人的ではありますが、生成AIを使うと開発がどのくらい短縮できるのか? と思うと4割くらいかな? という気がします。つまり元の60%くらいまで縮む。イメージを図にしてみました。

開発全体は生成AIで60%くらいに短縮できる、ような?

もちろんコードを書くところ (水色の作業) の時間はかなり短縮します。いっぽう人間が関わるところ、つまり問題がなにかを見つけるところと、問題が解決したか検証するところは、基本的に変わらないです (黄色の作業)。また考える時間も、あるていど短縮するけれどそんなに劇的に「速く考えられるように」はならないなあと感じています (緑色の作業)。

あまり変わらないよね、と感じる部分を短縮しようとするのは乱暴なやり方だと思いますし、実際乱暴なやり方がこれから増えていくんだろうなと悲観してもいます。乱暴というのは、速いけれど質が悪いということです。見落とされる、切り捨てられる要素が多いということでもあります。とりわけ人間に対してしわ寄せされるんでしょうね。悲しい。

生成AIにやってもらうことと、参加スタイルの整理

最後にまとめです。

生成AIにやってもらうこと

  • コーディング・実装
    • 仕様を実装、テストしてもらう
    • UI修正、見た目の調整
    • Issueへの対応とPull Requestの作成
    • 曳光弾開発をお任せ。AWS Amplify、CDK、外部サービスへの接続など一気に
  • テスト・環境構築
    • テスト駆動開発をする
    • ユニットテストを書く、書けるようにリファクタリングする
    • ユースケースシナリオを元に Playwright でE2Eテストを書く
    • E2Eテスト用の実行環境を作る。LocalStack、Dockerコンテナなど
  • 設計・要件定義
    • 設計の選択肢を作ってもらう。モジュール構成、サービス選定、テーブル設計など
    • 選択肢を比較評価するための観点出しと、評価のサポート
    • アーキテクチャを検討し、ADR (Architecture Decision Record) に書き残してもらう
    • ユースケースシナリオのバリエーションの追加
    • セキュリティ上確認すべき項目の整理
  • レビュー・ドキュメント作成
    • Pull Requestや実装したコードのレビュー
    • 人間の「仕様の理解」や「相談した内容の認識」のレビュー
    • 仕様変更や設計追加に伴うドキュメントの更新・同期
    • 長くなったチャットの議論を残す (Issue、ADR、仕様書など)
    • スキルやサブエージェント作成
  • 相談相手、頼れる先輩
    • 仕様の判断や、見落とし・落とし穴の検証
    • 既存コードの説明や、サンプルコードを作る
    • 一般的な知識の把握や、よくわからない技術の解説
    • 相談途中で論点を整理する。まだわからないこと、判断ポイントなど
    • 作業の進め方の相談相手と、TODOリストの作成

生成AIの参加スタイル:

  1. 自分 (人間) ができる、完成形を100%想像できること → 一発でやってもらう
  2. 情報や検討が必要、わからない点があること → 選択肢を作ってもらう
  3. それ以外 (何がわからないかわからない、など) → 伴走してもらって相談する

あくまで2026年2月時点 (もう3月になってしまった!) でのメモでした。

『指輪物語 運命の旅』ソロプレイしてみました

ボードゲーム『指輪物語 運命の旅』を開封し、1回ソロプレイしてみました。どんなゲームか知らず買っておいたもので、前情報もほとんどなしでしたが、久しぶりにワクワク感とドキドキ感を味わえました。ルールとかの話は基本触れずに、ゲームをやってみた体験や感じたことを簡単に紹介します。

どんなゲーム?

  • 1-5人の協力型ゲーム。今回は1人でやってみました
  • プレイ時間は60-150分ということですが、今回は開封から1回プレイして負けるまで、4時間くらいでした
  • 力の指輪を破壊すると勝利だが、その前に「目的」をいくつか達成しないといけない。まっすぐモルドールに向かえばいいわけではない
    • 目的はカードを引いて決めます。今回はカードを引くのではなくて、マニュアルにある初回プレイおすすめセットを選びました。「裂け谷でエルフを味方にする」「アイゼンガルドを占拠」「ゴンドール、ローハン、エルフの軍勢をそろえてサウロンに挑戦する」という3つの目的で、これは3つとも達成できたんですよね。
  • キャラクターもたくさんいて、プレイヤー1人で2キャラクターを動かします。今回はやはりおすすめの、フロド・サム、メリー・ピピン(これは2人で1キャラあつかい)、ガンダルフ、レゴラス、エオウィンでした
  • キャラクターが中つ国じゅうを駆けずり回っていろいろな条件を満たすのと同時に、軍勢を動かして拠点防衛したり攻め込んだりする要素もある。ファンタジーの王道が展開して胸熱
  • パンデミック型、ということです。私はパンデミック以外はわからないですが、ルールの理解がしやすいというくらいで、遊んだ感覚はずいぶん違った気がします

開封

箱が大きくて重いです。開けたら中身もギッシリでした。

バラドデュアを模したダイスタワーが (組み立て式)。ダイスタワーでダイス振るの嬉しいですよね。

マニュアルを読みながら1人プレイのセットアップをしました。ぜんぜんスペースが足らなかった。なんというか、中つ国の大きなマップ (ボード) に多様なコマが並んで、ナズグルが空を飛んでいるだけで、めっちゃテンション上がりますね!

黒くて大きいのは空飛ぶナズグル、小さくて赤・青・緑などがあるのは軍勢で、赤が敵、それ以外は自由の民の軍勢です。青がゴンドール、緑がエルフ、など。エドラスにはエオウィン、遠く左上 (北西) のホビット庄にフロド・サム、メリー・ピピン、ちょっと離れてガンダルフ。真ん中上の闇の森にレゴラス。

敵の軍勢 (赤い小さいやつ) はカードを引いて配置するんですが、今回アイゼンガルドにすごい集まっちゃってヤバそうです。8個いるのかな。手前にエオウィンが茶色いローハン軍を連れていますが、かきあつめても3個しかいない。

旅の仲間は足が速い

ソロプレイでは1人で4キャラクター、加えてフロド・サムを動かします。4キャラクターは順番に動かせて、そのあいだにフロド・サムはちょっとずつ動かせる。誰かが活躍しているあいだにじわじわ進んでいく感じが、なかなかそれっぽいです。

とはいえ同じ場所にいるキャラクターは移動アクションで一緒に移動できるので、エリアドールにいるメリー・ピピンとガンダルフがフロド・サムを連れてガンガン移動できます。ガンガン移動してすぐ裂け谷に到着。裂け谷ではハートを3つ使うとエルフが味方になるんですが、ハート?

このゲームにはリソースのようなものがあって、ハート、マント、武器、指輪の4種類があります。手札にこのいずれかがついているので、必要な時は手札で支払います。ハートがついたカードを3枚使えばいいわけです。しかし手札は上限7枚なので、思うようには集められない。そこで同じ4種類のトークンもあって、これはカードを「準備」アクションで使うとトークンに引き換えられます。安息地という、拠点みたいなところにいるときしか「準備」はできません (しばらく勘違いしてました。あとソロだと地域の縛りもある)。安息地は裂け谷とかロスロリエンとかミナス・ティリスとかそういうところ。

メリー・ピピンは特殊能力でハートを生み出せるので、カードも使って無事エルフを味方にしました。これで目的1つ達成です。さらにエルフの軍勢を招集して、しかもキャラクターと一緒に連れて行くこともできます。移動しながらどんどん軍勢を集めていけるのがダイナミック。敵軍勢と遭遇したら戦闘アクションができるんですが、戦わずにすれ違ってもいいので、ガンガン進めます (というふうにルールを理解したんだけど、合ってるのかな……?)。

というわけでアイゼンガルドをなんとかすべく、みんなでヘルム峡谷に集まったの図。エオウィンはローハン軍をじゃんじゃん招集できて、いまは5個に成長。アイゼンガルドにいた大軍勢が、いま1マス移動してます。カードによって敵軍も増えたり移動したりするんですね。

アイゼンガルド正面突破

メリー・ピピンはフロド・サムを連れてゴンドール方面に避難し、エオウィンとガンダルフでアイゼンガルドに向かいます。そしてアイゼンの浅瀬で衝突! 戦闘はダイスを振って解決します。勝ったり負けたりするんですが、ここに出た目は「ナズグル」で、一方的に被害が増えてしまいます。ところが! エオウィンには特殊能力があって、戦闘でナズグルが出てくると倒せてしまいます。ここでは1体倒しましたが、このあとすぐ2体目も倒してしまいました。アングマールの魔王は2人いたんですね。

エオウィンとガンダルフが一緒に軍勢を連れて移動しているので、戦闘の回数もふえてはかどります。さらに闇の森からエルフの弓兵を連れてレゴラスが参戦、ナズグルもめっちゃ集まってきました。レゴラスは特殊能力アクションで、敵の赤いのを1個倒したりナズグルを追い払ったりもできます。

そしてこの後、無事アイゼンガルドは占領でき、安息地となりました。敵が湧いてこなくなるのがありがたいですね (ここはパンデミックの根絶とちょっと近いのかな? でも条件がだいぶ違うなあ)。占領するときは武器リソースが必要ですが、ちょうどめくったカードに入ってて助かりました。トークンは1個も持ってなかった。アイゼンガルド占領で、2つめの目的が達成できました。なおアイゼンガルドとローハンは別領域になっていて、ナズグルが着いてこなかったので、エオウィンのナズグル狩りはできませんでした。

動かなければ見つからないが進まないと勝てない

この間メリー・ピピンはゴンドールへ逃走、フロド・サムはミナス・ティリスにずっと籠もっています。動かなければ敵に見つかる心配もないし……そうそう、フロド・サムは指輪のせいで敵に見つかる心配があるんですね。移動するとき、敵軍勢やナズグルがいると、「見つかっちゃうダイス」を振ることになります。ダイスの目によってはフロドが希望を失ってしまいます。希望がゼロになるとゲームオーバーなんですが、マントを使ってダイスをパスしたり、ハートでサムにかばってもらったりという選択肢もあって、これまた悩みどころです。

さっきはローハンのドンパチでナズグルもサウロンの目もそっちに引きつけられていて、フロド・サムにとっては動きやすかったんですね。そっちを片付けたエオウィンとガンダルフがゴンドールに入ってきたのに合わせて、フロド・サムはするっとイシリエン (オスギリアス) へ移動。敵もナズグルもいなければ、ダイスは振らなくていいのでした。

ガンダルフはゴンドール軍を集めに南へ行きました。ガンダルフは飛陰のおかげで、1人のとき足が速いのです。強い。

そして北イシリエンに大軍勢が終結。これで3つめの目的「サウロンに挑む」を達成! ゴンドール、ローハン、エルフの軍勢を決められた数連れてくるのが条件です。ガンダルフが連れてるぶんはなくてもよかった。遅れてきたガンダルフ、いえいえもちろんねらい通りに決まっている。隠れてたフロド・サムと出会えてますね (ゲーム的には意味はない)。

いよいよ滅びの山で指輪を滅ぼす……あれ、指輪持ってる?

これでモルドールの敵軍がすべてウデュンに集まり、フロド・サムの通る道ががら空きになります。この一瞬はナズグルもいないので見つかる心配なし。ただしミナス・モルグルに向かう道はマントのアイコンが2つ書いてあります。これは通るだけでマントが必要ということ。トークンとカードを貯めているけれど、滅びの山まではけっこう遠いしまだまだマントが必要だなあ。大丈夫かな。

北イシリエンに終結した自由の民の軍勢と、ウデュンの赤いかたまり。さあ総力戦だ!と思ったら、北イシリエンとウデュンの間の道はマントが4つ必要とのこと。そんなに払えないよ。敵軍も移動してこないし、なんとここで一戦も交えずにらみ合いです。戦闘にならないからサウロンの目も引きつけられないし、ナズグルもモルドールに集まってきちゃった。マントが足りないので動けないフロド・サム。

そして最後の指輪を滅ぼす条件をよく見たら、指輪リソースが5個必要とのこと。指輪リソース? そんなの持ってないぞ……と気づいたメリー・ピピン、リョバニオンからドル・グルデュア、モリアを抜けてルダウアと、トークンを集めに奔走します。いちばん危険なところを通ってないかい君たちすごいな (なおルールの勘違いをしていて、準備アクションは安息地じゃないと使えないのを無視してました)。

偉い人たちが北イシリエンで大軍勢を連れて役立たずになっているあいだ、各地を駆け回ってリソースを集めてくれたメリー・ピピンのおかげで、いよいよ滅びの山へ行ける……! と思った矢先、思わぬ展開が。敵カードの按配であまり動かないでいた敵軍勢が、カードの按配でするするっと動いて、無防備な闇の森のエルフの王国を占領してしまいました。この凶事でフロドの希望はマイナス3、一気に0=絶望に。指輪所持者は旅の半ばで心が挫けてしまい、あらぬところで「私のものだ!」と叫んでナズグルにぶら下げられて行ってしまったんでしょうね、たぶん。ゲームオーバーです。

ボード左の希望カウンターがゼロ、絶望になっています。右上の奥の方、闇の森の北に赤い軍勢がいますが、あれが敗因です。スランデュイルごめんね。

感想

指輪物語の物語を追体験するようなゲームではなく、キャラクターと目的の組み合わせに応じた様々な可能性や展開を楽しむゲームのようです。カードとサイコロの運の要素もかなり影響強そうですが、勝ちに行くというよりも、戦略を考えながら想定外の展開に対応しつつギリギリで勝てたり、勝てなかったりという、すべてを楽しむゲームですね。場面場面を楽しむゲームという気もします。

アイゼンガルドが強すぎて驚いたり、そしたらエオウィンがナズグルハンターでさらに強すぎて驚いたり、レゴラスにいいところがなかったり、ナズグルが群れをなしていたり、黒門不通でまさかのにらみ合いになったり、メリー・ピピンがとんでもない大移動をしたり、それぞれが指輪物語の世界観の中で創造力を刺激してくれるのが楽しかったです。

セットアップもたいへんだしルールも複雑で、この規模のゲームに慣れていない私にとっては難易度高かったです。ソロでやるにはだいぶ踏ん切りを付けないといけなさそう。人とやるにも説明だけでたいへん。練度の高いみなさんなら大丈夫なんだろうな。

初回でもあったためルールの勘違いや手順の混乱があって、正確なプレイにはなっていないと思います。雰囲気は掴めたんじゃないかなと思っていますが、そうでもないかもしれません。