Claude Code が書きがちな Python コードを読めるようになろう①

はじめに

Claude Code などのコーディングエージェントは、タスクを進める途中で、その場で Python コードを書いてインラインで実行することがあります。 gh の JSON 出力を整形したり、SQL ファイルから件数を数えたりと、シェル芸だけでは面倒な処理を Python で埋めてくることが多いです。
自分の Claude Code の会話履歴（ ~/.claude/projects/*.jsonl ）を全て集計してみたところ、意外にも、その場で書いて実行するコードは 10 プロジェクトを合わせても 20 件強でした。ただし、出てくる場所と使うパターンは決まっていて、標準ライブラリのごく一部で足りるものがほとんどです。
この記事では、集計から見えてきた頻出パターンを整理して、Claude が書いた Python コードを読むために押さえておきたい要素をまとめます。

Claude が Python を呼ぶ 3 つの形

Claude が Python を実行する方法は、大きく 3 つに分かれます。

python3 -c '...' … 1〜2 行のワンライナー。シェルパイプの一部として使う
python3 << 'PY' ... PY … ヒアドキュメント。数十行の処理をシェル履歴に残す
python3 foo.py … Write ツールで .py ファイルを書いてから実行

私の履歴では、 -c が 13 件、ヒアドキュメントが 7 件、 .py ファイルの作成は 2 件でした。1 回きりの処理なら -c かヒアドキュメント、繰り返し使うものだけを .py に書き出す使い分けになっています。

パターン 1: JSON をパイプで整形する

もっともよく出てくるパターンです。 gh api や curl の JSON 出力から、必要なフィールドだけを抜き出すのに使います。
たとえば、GitHub の PR コメントを整形する処理はこのような形になります。

 gh api repos/foo/bar/pulls/123/comments \ | python3 -c "import sys, json; d = json.load(sys.stdin); print(json.dumps([{'user': c['user']['login'], 'path': c['path'], 'body': c['body']} for c in d], ensure_ascii=False, indent=2))"

1 2	gh api repos/foo/bar/pulls/123/comments \ \| python3 -c "import sys, json; d = json.load(sys.stdin); print(json.dumps([{'user': c['user']['login'], 'path': c['path'], 'body': c['body']} for c in d], ensure_ascii=False, indent=2))"

シェルの引用符の中に詰め込まれていて読みにくいので、Python コードの部分だけを取り出して整形すると、次の処理をしていることが分かります。

 import sys, json comments = json.load(sys.stdin) result = [ {'user': c['user']['login'], 'path': c['path'], 'body': c['body']} for c in comments ] print(json.dumps(result, ensure_ascii=False, indent=2))

import sys, json

comments = json.load(sys.stdin)

result = [

{'user': c['user']['login'], 'path': c['path'], 'body': c['body']}

for c in comments

]

print(json.dumps(result, ensure_ascii=False, indent=2))

見るべき要素は 3 つあります。

json.load(sys.stdin) … 標準入力の JSON をパースして Python のオブジェクトに変換します。ファイルから読むときは json.load(open(path)) 、文字列から読むときは json.loads(s) です。名前が似ていて紛らわしいのですが、末尾の s は string の s と覚えておくと迷いません。
内包表記 [{...} for c in comments] … リストを 1 行で組み立てる書き方です。詳しくは次の節で説明します。
json.dumps(..., ensure_ascii=False, indent=2) … Python オブジェクトを JSON 文字列に戻します。 indent=2 は改行付きで整形、 ensure_ascii=False が日本語プロジェクトでは特に重要です。
loadと同様にこちらも json.dump() 関数を使ってファイル等に書き込むこともできます。

内包表記

内包表記は、 for 文で空のリストに要素を append していく処理を、1 行で書く書き方です。上のコードの result = [...] の部分は、次のループと同じ意味になります。

 result = [] for c in comments: result.append({'user': c['user']['login'], 'path': c['path'], 'body': c['body']})

result = []

for c in comments:

result.append({'user': c['user']['login'], 'path': c['path'], 'body': c['body']})

後ろに if を付けると、条件で絞り込むこともできます。

 # body が空でないコメントだけを対象にする result = [ {'user': c['user']['login'], 'body': c['body']} for c in comments if c['body'] ]

# body が空でないコメントだけを対象にする

result = [

{'user': c['user']['login'], 'body': c['body']}

for c in comments

if c['body']

]

[...] を {...} に変えて key: value の形で書くと、辞書内包表記になります。

 # ユーザー名をキー、コメント本文をバリューにした dict を作る by_user = {c['user']['login']: c['body'] for c in comments}

1 2	# ユーザー名をキー、コメント本文をバリューにした dict を作る by_user = {c['user']['login']: c['body'] for c in comments}

{...} の中に key: value ではなく単一の式を書くと、セット内包表記になり、重複を除いた集合が得られます。

 # コメントを付けたユーザー名の集合 users = {c['user']['login'] for c in comments}

1 2	# コメントを付けたユーザー名の集合 users = {c['user']['login'] for c in comments}

丸括弧 (...) にするとジェネレータ式になります。要素を都度生成するので、全要素をメモリに載せずに sum や any に流すときに便利です。

 # body の長さの合計を、途中のリストを作らずに求める total = sum(len(c['body']) for c in comments)

1 2	# body の長さの合計を、途中のリストを作らずに求める total = sum(len(c['body']) for c in comments)

内包表記は Python で頻繁に出てくる書き方なので、 for と if の並び順、括弧の種類ごとの意味を掴んでおくと、Claude が書くコードもすんなり読めるようになります。

ensure_ascii=False の意味

json.dumps はデフォルトで、非 ASCII 文字を \uXXXX 形式にエスケープします。たとえば {"name": "田中"} は {"name": "田中"} と出力されます。JSON 仕様上は正しいのですが、人間には読めません。
ensure_ascii=False を付けると、日本語がそのまま出力されるようになります。Claude が書くコードでは、日本語を扱うプロジェクトのときにこれが必ず付いていました。

パターン 2: 行番号でファイルを書き換える

sed -i でもできる処理ですが、複数行の書き換えを dict でまとめて記述したいときや、事前チェックを入れたいときには Python で書く方が確実です。
たとえば、Markdown の表の特定行の末尾に列を追記する処理です。

 python3 << 'PY' path = "docs/api.md" with open(path, encoding="utf-8") as f: lines = f.readlines() suffix = { 12: " 認証 | 権限 |", 13: " ---- | ---- |", 14: " 不要 | 全員 |", 15: " 必要 | 管理者 |", 16: " 必要 | 管理者 |", 17: " 必要 | 本人のみ |", 18: " 必要 | 本人のみ |", 19: " 必要 | 管理者 |", } for ln, suf in suffix.items(): idx = ln - 1 stripped = lines[idx].rstrip("\n") assert stripped.rstrip().endswith("|"), f"line {ln} not a table row: {stripped[:40]!r}" lines[idx] = stripped + suf + "\n" with open(path, "w", encoding="utf-8") as f: f.writelines(lines) PY

python3 << 'PY'

path = "docs/api.md"

with open(path, encoding="utf-8") as f:

lines = f.readlines()

suffix = {

12: " 認証 | 権限 |",

13: " ---- | ---- |",

14: " 不要 | 全員 |",

15: " 必要 | 管理者 |",

16: " 必要 | 管理者 |",

17: " 必要 | 本人のみ |",

18: " 必要 | 本人のみ |",

19: " 必要 | 管理者 |",

}

for ln, suf in suffix.items():

idx = ln - 1

stripped = lines[idx].rstrip("\n")

assert stripped.rstrip().endswith("|"), f"line {ln} not a table row: {stripped[:40]!r}"

lines[idx] = stripped + suf + "\n"

with open(path, "w", encoding="utf-8") as f:

f.writelines(lines)

見どころは次のとおりです。

with open(...) as f:
with 文で開いたファイルは、ブロックを抜けるときに自動的に閉じられます。例外が起きても閉じてくれるので、明示的な close() を書かなくて済みます。Python でファイルを扱うときの定番の書き方です。
encoding="utf-8" を明示する
macOS や Linux ならデフォルトが UTF-8 のことが多いのですが、Windows や一部の環境では別のエンコーディングが使われる場合があります。日本語を含むファイルを扱うときは、 encoding="utf-8" を明示しておくと環境依存の事故を避けられます。
readlines() は改行を含む
f.readlines() で返るリストの各要素は、末尾に \n を含んだままです。行末に追記する場合は、いったん rstrip("\n") で改行を除去し、追記後に + "\n" で戻します。
行番号は 1-indexed で受け取り、 idx = ln - 1 で 0-indexed に
エディタや grep -n が表示する行番号は 1 から始まりますが、Python のリストは 0 から始まります。人間が指定する値は 1-indexed で受け取り、内部で - 1 してから使うと、書き手にも読み手にも自然です。
assert で前提を明示する
assert stripped.rstrip().endswith("|") は、書き換える行が表の行であることを事前に確認しています。想定外の行を書き換えるとファイルが壊れるので、前提が崩れたら止まるようにしておきます。ちょい仕事の Python コードでも、こうした最低限の防御は入れる価値があります。エラーメッセージには、次で説明する f-string を使っています。

f-string f”…”

Python の文字列リテラルには、先頭にプレフィックスを付ける書き方があります。よく使われるのが f-string で、 f"..." の形で書きます。中括弧 {} の中に変数や式を書くと、その値が埋め込まれた文字列になります。

 name = "田中" count = 3 print(f"こんにちは、{name}さんの投稿は {count} 件です") # こんにちは、田中さんの投稿は 3 件です

name = "田中"

count = 3

print(f"こんにちは、{name}さんの投稿は {count} 件です")

# こんにちは、田中さんの投稿は 3 件です

{} の中には、変数だけでなく式も書けます。

 items = [1, 2, 3] print(f"合計: {sum(items)}")

1 2	items = [1, 2, 3] print(f"合計: {sum(items)}")

数値のフォーマット指定は、 : の後ろに書きます。

 price = 1234.567 print(f"{price:.2f}") # 1234.57 (小数点以下 2 桁) print(f"{price:,.0f}") # 1,235 (3 桁区切り、整数)

price = 1234.567

print(f"{price:.2f}") # 1234.57 (小数点以下 2 桁)

print(f"{price:,.0f}") # 1,235 (3 桁区切り、整数)

さらに、 !r を付けると値の repr() が埋め込まれます。文字列のクォートや改行の見え方をそのまま残したいときに便利です。上のコード内で使った f"line {ln} not a table row: {stripped[:40]!r}" も、行の内容をそのままの見た目でエラーメッセージに含めるためのものです。

 s = "hello\n" print(f"got: {s!r}") # got: 'hello\n'

1 2	s = "hello\n" print(f"got: {s!r}") # got: 'hello\n'

-c とヒアドキュメントの使い分け

-c は 1〜2 行の処理までが目安です。シェルの引用符の中に Python コードを書くため、複数行のインデントを含む処理は書きにくくなります。文の区切りは ; を使いますが、 if や for の直後には使えないので、単純な逐次処理に限定されます。
インデントが必要になったらヒアドキュメントに切り替えます。開始タグ PY と終了タグ PY の間に Python コードをそのまま複数行で書けます。

 python3 << 'PY' total = 0 for i in range(10): if i % 2 == 0: total += i print("even sum:", total) PY

python3 << 'PY'

total = 0

for i in range(10):

if i % 2 == 0:

total += i

print("even sum:", total)

開始タグは 'PY' のようにシングルクォートで囲むのが定番です。囲まないと $var などがシェル側で展開されるため、Python コード側に $ や ` を含む場合の事故を防げます。

さいごに

これからも、Claude Codeが出力するPythonコードを理解できるようになるために、連載していきたいと思います。

日	月	火	水	木	金	土
			1	2	3	4
5	6	7	8	9	10	11
12	13	14	15	16	17	18
19	20	21	22	23	24	25
26	27	28	29	30	31