Naoki URAI/30年選手が、2026年になってようやくAI活用が腹落ちした話

Created Fri, 20 Mar 2026 20:33:41 +0900 Modified Fri, 20 Mar 2026 13:55:28 +0000
4222 Words

(約)30年選手が、2026年3月になってようやくAI活用が腹落ちした話

こんにちは。ソフトウェア開発を30年くらいやっているエンジニアです。
人が嫌がる仕事をやっていたら、なんとなくインフラからフロントエンドまで見れるようになっていました。

そんな自分ですが、正直に言うと、AIを日常的にちゃんと使い始めたのは今年（2026年）からです。 だって AI はみんな嫌がってなかったからね。

  • たしかに便利ではある

……しかし、何か実務にマッチしきれていないモヤモヤがぬぐえずに AI 元年から 3 年が過ぎる…のですが

今年になって、ようやく、その違和感に気付きました。

ワイ色に染まってないのが嫌なんやで

AIがすごいこと自体は、もう疑いようがありません。 でも結果がズレたときの「token返せよ！」感は大きいです。

私は普段の仕事でざっくり以下の事をルーチンとして回しています。

  • 要件を整理する
  • 前提・制約・責任範囲を明確にする
  • UseCase と Actor を整理する
    • I/F のたたき台を作る
    • 正常系と主要な異常系を整理する
  • UseCase の優先度を決める。途中で状況が変わったら見直す
  • NFR を洗い出す
    • I/F を見直す
    • システム的なリスクを洗い出す
      • 不慣れな領域があるかを洗い出す
  • 必要に応じて DDD の観点で境界や責務を整理する
  • ここまでを踏まえて外部設計する
    • 必要に応じて ERD を書き始める
  • 失敗は次に持ち越せる形にする

フェーズに応じて、それぞれをドキュメントやコードとしてアウトプットし、次のサイクルで更新していく。

無理やりまとめましたが、改めて結構手順は多いです。

この手順を調教すれば、なんかワイにもAIの息遣いが聞こえてくるんじゃない？と思い始めた次第です。

とりま、チケット１つを、ワイのやり方で AI 調教する

CLAUDE.md を、プロジェクトのルート、各 component 単位で書く。 これ自体は、普通に推奨されているので特筆することはありません。

自分はチケットごとに _work/チケット番号/CLAUDE.md のようなファイルを作って、そのチケット専用の前提を書いています。

ちなみに、複数リポジトリを担当することが多いので、${HOME}/_work/ を作って実際のリポジトリにはシンボリックリンクしてます。

git config --global core.excludesfile しとくの忘れんなよ。小僧。

例えば、こんな内容です。いわゆる 1 ユースケースレベルの内容です。(直近はインフラ触ってたのでこんな例しか思いつかぬ)

# チケット: ABC-123

## 目的
GitHub Actions の OIDC ロールに対して、hydra / hydra-migrator 用の ECR push 権限を追加する。

## 制約
- 既存の本番ワークロードには影響を与えない
- 変更対象は必要なリポジトリとアクションに限定する
- 可能な限り広いワイルドカード権限は避ける

## 既知の状況
- 既存の OIDC ロールには、一部リポジトリ向けの ECR 権限がある
- 失敗したアクションは ecr:InitiateLayerUpload
- 対象環境は ho-hogehoge-1

## 今回やらないこと
- OIDC policy 全体の設計見直しはしない
- 無関係な IAM 課題の整理は同じ変更に含めない

## 今回期待する作業
- 現在の権限不足箇所を特定する
- 最小限の IAM policy 修正案を出す
- レビュー観点と副作用の有無を整理する

ここでやっているのは、あくまで「今回のタスクの前提とゴールを揃える」ことです。

ただ、みなさんも、最初の見積では「こんな感じか」とそろばんを弾いたものの

着手すると、あれよあれよと 膨らむ工数 に メンタルの削り節 が舞う経験をお持ちだと思います。

それは普通です。エンジニアリングはどんどん便利になっていきますが、それと同時に求められる要件や覚える・気を付けるべき認知負荷は、ここ数年で相当上がっています。

「いつまでにできる？」とエンジニアに聞くと目をそらしがちなのはしようがないんです。だって人間だもの。

なので、ここから改めて Plan を実行し、どれくらいの作業項目があるのかを洗いだします。

# Plan (ほんとはコードレベルでモリモリ出てくる)

1. 現在の OIDC policy を確認する
2. 不足している ECR アクションと対象リポジトリを特定する
3. push 失敗を解消できる最小の policy 変更案を作る
4. hydra / hydra-migrator の両方をカバーできているか確認する
5. リスク、レビュー観点、ロールバック方法を整理する

ここでは本当にザックリ書いてますが、あんなファイルにこんなファイルを編集したり、追加したりと、commit PR したときに驚くようなファイル数でレビュアーを泣かせてしまう未来の自分が想像できるかもしれません。

なので、範囲が大きすぎる場合は、この Plan を適切に分割するよう AI にお願いします。

  • Plan を 着手可能順に ABC-{バックログNo}-{概要}/CLAUDE.md へ分ける。これをサブタスクとする。
  • 各 サブタスクには、少なくとも以下を含める
    • 事前条件
    • 実装内容
    • 受け入れ条件
    • テスト内容（手動でのコマンド実行を含む）
  • 他の サブタスク がブロック要因になる場合は、事前条件にリンクを書く
  • 1つの サブタスク で触る作成・更新ファイル数は、できるだけ 5 個程度 または 計 500 行程度に抑える
  • 外部通信や高負荷などの技術的リスクがあるものは、必要なら mock,stub,docker などで可能な限りローカルで環境を再現、検証を優先する
  • 事前条件がない、またはすでに解消済みのものは、並列可能サブタスクとして扱う

すると、こんな感じでチケット(親Plan)を細分化してくれます。

_work/
┗─ ABC-123/
   ┣─ CLAUDE.md
   ┣─ ABC-124-current-state/
   ┃  ┗─ CLAUDE.md
   ┣─ ABC-125-minimal-policy-update/
   ┃  ┗─ CLAUDE.md
   ┗─ ABC-126-review-side-effects/
      ┗─ CLAUDE.md

親チケットの CLAUDE.md ではチケット全体の前提や制約を持ち、
各サブタスク配下の CLAUDE.md では、その サブタスク に閉じた前提・作業内容・受け入れ条件を持たせるようにしています。

サブタスク のイメージはこんな感じです。

# ABC-124-current-state

## 事前条件
- なし

## 実装内容
- 現在の OIDC policy を確認する
- ECR push に必要な action の不足を洗い出す
- 既存リポジトリごとの権限差分を整理する

## 受け入れ条件
- 不足 action の一覧が明確になっている
- 対象リポジトリが特定できている
- 追加が必要な policy の対象範囲が説明できる

## テスト
- IAM policy の定義内容を確認する
- Terraform plan に影響する箇所を洗い出す

# ABC-125-minimal-policy-update

## 事前条件
- [ABC-124-current-state](../ABC-124-current-state/CLAUDE.md)

## 実装内容
- 必要最小限の ECR push 権限を追加する
- hydra / hydra-migrator のみを対象に絞る

## 受け入れ条件
- 必要な action が不足なく含まれている
- 無関係なリポジトリへの権限拡大がない
- 差分がレビューしやすい単位に収まっている

## テスト
- Terraform plan を確認する
- 権限対象が想定どおりかレビューする

この分け方をしておくと

  • レビューしやすい
  • 依存関係が見える
  • 並列化できる(ものが見つかる)
  • リスクの高いものを先に潰せる

という、人が係る実務へ違和感なく流せるし、最悪 AI が落ちても人のキャパシティでなんとかカバーできる粒度になります。

サブタスクを終えるごとに Plan を更新する

サブタスクを1つ終えるごとに、Claude に最新のブランチ状態と残タスクに対して、毎回こんなことを確認しています。

  • 依存関係は変わっていないか
  • リスクの見積もりは今の状態で合っているか
  • スコープを削れるところ、逆に足りないところはないか

これはAIに限らずですが、最初に良い計画を作ることより、途中で更新し続けられることのほうが実務に合ってる と感じています。

だって、世の中変更だらけじゃない。

感覚としては、1つのチケットの中に小さなプロジェクトを作って、
その単位ごとに小さく PDCA を回している イメージです。

失敗は反省ログに戻して、次回に持ち越す

テストやE2Eが失敗した時も、AI に修正させると思いますが、なぜ失敗したか？を覚えさせます。

  • 今回はなぜ失敗したのか？
  • 今回の失敗はルール化すべきか？
  • 次回の Plan にどう反映するか？

を考えてもらって、理由を CLAUDE.md の反省ログに追記しています。

## Lessons Learned
- 1つの action エラーだけを見て IAM 権限を広げすぎない
- ECR push エラーを直すときは、必要な upload 系 action をまとめて確認する
- Terraform の IAM 修正では、「今回必要な修正」と「ついでに直したいこと」を分ける

ただ、一回反省文を書かせたからと言って 100% 襟を正してくれる訳ではないので

たまに「これを実装したいんだけど、ルール覚えてる？」と @ で確認してあげてください。

(おまけ) JIRA と サブタスク を同期する

仕事上、JIRA も使うんですが、それとの同期も自動化しています。
もちろん「PRを見れ!!!」という声はあるかもしれませんが、プロジェクトはエンジニアだけで動いているわけではありません。

やはり 誰でも見える化 は大事です。

流れとしてはこんな感じです。

  1. サブタスク完了
  2. Claude に進捗サマリーを書かせる
  3. 同期スクリプトで JIRA に進捗を反映する
    • 説明欄やコメントに、進捗・エラー・気になったことを残している
  4. 必要に応じてステータス遷移も行う

ちなみに同期スクリプトは、言語指定せずに AI にお願いしたら Python になりました。
shell で来るかなと思っていたのは内緒です。

# upsert_subtask の中では、subtask-***.md の内容をそのまま JIRA API に渡しています。
upsert_subtask.py ABC-123 ABC-124 ABC-125 ...

ちょっとまって！余計に面倒じゃない？

多分、自分が社長で一人で全部やって、死んでからも面倒を見るプロダクトであれば、ここまでやりません。

ホイホイ作ると思います。

曲がりなりにも、会社組織に属し、責任あるプロダクトを任せてもらっている以上、多くのメンバーと関わります。

  • 自分が離脱しても回る状態を作りたい
  • 属人化を減らしたい
  • 引き継ぎ可能な形にしたい
  • AI はもちろん前提だけど、AI が無くても開発が止まらないようにしたい

一応いい歳しているので、常識的な事を考えているのです。

実際にやってみてどうだったか

“AIにうまくやってもらう” のではなく、“自分のやり方を渡す”

ことで、

  • ﾝだよこれ？！

ではなく、

  • この指示や制約が足りないのか。なるほど。

と見る事が出来るようになり、AI の息遣いが分かるようになってきました。

(*´Д｀)ハァハァハァ

まとめ

最初は雑に「つくって」と指示して、entry point の .go にゴッソリ書かれてしまった事で 「…めんどくさい…」 と悶々としていましたが、AI に対して指示した事は、特別なことではありません。

  • まず前提を書く
  • チケット単位で Plan を作る
  • 途中で見直す
  • 失敗を次回に活かす

言ってしまえば、それだけです。

ただ、それをAIにも分かる形で渡すようにすると、思った以上に回り始めますし、何より自分の認知負荷がものすごく軽減されました。

自分なりの仕事の進め方をテンプレート化・再利用する という感覚のほうが近いかもしれません。

案外、しばらくの間 AI の使い方やエージェントを吟味するというより、自分が普段どう考えて仕事をしているかを再定義する というのが、AI との付き合い方になるかもしれませんね。

2 ~ 3 年したらまたパラダイムがシフトってるかもしれんけど