システムの監視ポリシーについて述べる。
監視の定義
あるべき状態が保たれていることを、適切な頻度で確認し続けること。そして保たれなくなったら検知すること。
- あるべき状態の例
- サービスが動いている
- SaaSの費用をちゃんと払っている。そして金額も妥当な範囲に収まっている
- バッチが時間内に終わっている。途中で停止せず処理が最後まで行われている
-> どういう状態であってほしいのかから入る。手段からスタートしない。
- 適切な頻度で確認し続けることの例
- DBの停止や再起動は起きたら即
- WEBサービスの外形監視はN分おき
- 指標のトレンド確認は週次でいいことがほとんど
-> 対応の緊急性に応じて合理的に設定。やりすぎはコストを増やす。
- 保たれなくなったら検知することの例
- 緊急性の高いアラートはメールだけでなく電話も使って受け損ねを防止
- 重要だが緊急ではないエラーのアラートは随時メール
- 重要でも緊急でもないエラーはサマリーレポートを毎日決まった時間に確認
-> こちらも緊急性に応じて受ける方法を用意。監視漏れも監視疲れもよくない
なにを監視すべきか、すべきでないか
監視対象は、まずあるべき姿を洗い出し、そこからどう正常性を確認するのかを考えていく。あるべき姿はプロジェクトの性格によって異なるため、プロジェクトの性格に応じてカスタマイズする。監視内容によってはアプリケーションに可観測性のための機能を持たせる。どんなサービスでもこれだけやっておけば妥当と保証できるチートシートは元から存在しないのであり、手段から対象を決めるべきでない。
監視対象の違いの例)
- B2Cの情報提供系サービス : 24時間365日サービスが落ちないこと、レスポンス速度も妥当であること -> サービスの外形監視、レスポンス速度の監視等
- バッチ処理系のサービス: 処理時間が突き抜けないこと、途中で止まっていないこと、また過去の実施時と比べて極端に取り扱うデータ量が減っていないこと -> 処理時間や実行結果をログでだすようにした上でのログ監視、アプリケーション組み込みの簡易なレポートを定期的に確認する等
また監視は対応とセットである。対応ノウハウの共有のため、可能なものは手順や判断基準をあらかじめドキュメント化しておく。それが難しいものは対応後に記録を残して関係者が（許されるならAIも）いつでも参照できるようにする。
ノイズアラートの防止
不要な監視は行わない。メンバーの疲弊やアラートの見落としを誘発するためである。
このため追加は本当に必要か検討した上で行う。一度追加してしまうと、実際はフォールスポジティブばかりで役に立たないアラートでさえ、責任問題となるリスクにより削除しづらくなる。
まず、アラートの発報を伴う監視は対応可能性とセットで考える。対応不要あるいは対応不能なことに発報すべきでない。
意味のあるアラートの例
- データベース用サーバーのメモリ残量のひっ迫 -> スケールアップやスケールアウト
- 特定IPからの大量不正アクセス -> WAFやアプリケーションにフィルタ追加
意味のないアラートの例
- オートスケールの実行時にアラート -> 対応が必要ない
- AWSのCloudFrontの死活監視 -> 対応できることがない
具体例
ポリシーとしては上記のみであるが、理解の促進のためWEBアプリケーションを例にとって具体例を付け加える。
この場合、まずエンドユーザーつまり利用者にサービスが提供し続けられていること。ひっくり返すと、提供し続けられなくなるような事態になっていないこと（異常検知）、もしくはいずれ重大な障害が出ると予想されないこと（予兆検知）が必要である。この前提で、WEBアプリケーションで各レイヤごとに監視すると例えばこのようになる。
- ユーザー体験: 外形監視、レイテンシ監視など
- アプリケーション: ログ監視、エラー時の直接発報、ジョブキューの過剰滞留など
- インフラ: リクエストのエラー率（5XX）、アプリケーションサーバの稼働数（スケールアウトに関係）、マネージドサービスの強制メンテナンス予定、EOL予定、ドメインや証明書の残り日数など
次にそのサービスを続けていけること。このために具体的にはセキュリティやコストを監視する。
- セキュリティ: 脆弱性、マルウェア、悪意のあるアクティビティなど
- コスト: 通常ではありえない額の課金、Reserved Instance等割引サービスの残り日数など
また監視はアラートだけセットするのではなく、トレンドを見るためのメトリクスとそれをまとめたダッシュボードも用意する。問題の存在を告げるトレンドが出ていたら対応が必要である。例えばレイテンシが悪化していく一方であったり、メモリの残量が下がっていく一方であったりするなら、なんらかの不具合が隠れている可能性が高い。
一方で必要性の薄いアラート、有用性の低いアラートは流さない。
ログ管理について述べる。
ログを管理する目的
ログは開発・運用に欠かせないものであるから、適切に収集と保管を行う。
- 監視: 例）正常に動作していることを確認する
- 調査: 例）障害調査のための現状把握に使う
- 分析: 例）ユーザーの挙動から導線の有効性を確認する
- 監査: 例）記録されていることを見せて悪用をけん制する
ログの基本要件
ログは目的に応じ以下の要件を満たした状態で保存する。
- 重要度に応じて適切に分類されていること
- 検索および分析が可能な形式であること
- 個々の処理や操作を追跡可能であること
取得するログは例えば下記のようなものがあげられる。
- インフラやアプリケーションの重要な処理の結果。例）エラーやバッチの処理結果など
- ユーザーの動向記録 例）アクセスログ
- 設定変更などの重要な操作。例）管理権限を持つユーザーの追加
何を記録してはいけないか
セキュリティおよびコスト最適化の観点から、下記のようなログを記録してはならない。
- 機密情報（個人情報、パスワードやAPIキー等）
- 利用価値の低いログ(一時的なデバッグログなど)
- 出力しないか、あるいは受け入れ元でフィルタ/サンプリングする
いつまで保持するか
ログの保持期間は用途によって変更する。例えば下記のようにする。
- 本番環境の決済などの重要なログ -> 最低数年（関連の法令やガイドラインがあるなら必ず満たすこと）
- 本番環境のアプリケーションのエラーログ -> 最低1年
- 開発環境のログ -> 最低保持期間は定めないがおおむね数カ月
必要以上に保持しないほうがコスト最適化のためにはよいが、必要になった際に消してしまっているほうが通常は問題が大きいため、余裕をもって設定する。
保持期間を過ぎたログは、速やかに削除または適切にアーカイブする。
セキュリティ
ログの保全のため、業務に必要なものに対してのみ操作権限を与える。例えば下記のようにする。
- ログの閲覧は必要な人員のみ可能
- ログの削除は管理者のみ可能
- ログの改変は誰であれ禁止。どうしてもやむを得ない場合は、記録を残した上で特例措置として実施する（ブレイクグラス）
ログの保管場所
ログの保管はセキュリティが保て、かつ毀損しないよう十分な信頼性を持った手段で行う。例）AWS S3
ただし障害対応や監査対応に支障が出ない程度の時間で参照できること。
さまざまな権限付与方式
AIにGitHubを操作させる方法としては、HITL（Human In The Loop）、プロキシ利用、GitHub App、PAT格納などの方式があり、それぞれ利便性やリスクが異なる。単独で他のすべてに勝る方式はないため、用途に応じて選択するとよい。
| モデル | 基本方式 | 漏洩時の権限の寿命 | 効率性 | 流出リスク |
|---|
| HITL(Human In The Loop) | AIがアクセスできない場所から人間がghなどで操作を実行 | （AIにPAT/tokenを渡さない） | 人手が常に必要 | ありえない |
| プロキシ利用 | PATを格納したプロキシに中継させる | （AIにPAT/tokenを渡さない） | 使えるツールが限定され不便 | ありえない |
| GitHub App | GitHub Appが短命トークンを発行。それをAIが利用する | 短命 | 高い | ありえるが悪用リスクは限定的 |
| 直接トークン | PATをAIに直接付与 | 長命 | 高い | ありえる |
※ 流出リスクについて: 上記はあくまでAIによるPAT流出リスクについての評価である。オペミス等別の要因によって流出するケースは議論の外である。
使い分け
- 極めて高いセキュリティを求められており、わずかなリスクの可能性すら許容しがたい -> HITL
- PRスパム程度ならともかくPAT漏洩リスクの可能性は一切許容できない、あるいは諸事情でGitHub Appが使えない -> プロキシ
- 他の施策と合わせればインシデント発生時の被害を許容範囲内に抑えられる -> GitHub App
- 漏洩してもさして問題ない環境（実験用など）である -> PAT直渡し
利用方法
HITL
手動で利用するのと同じ。
AIはコマンドを指示したり、テキストを作ったりする程度である。
プロキシ利用
PAT/Tokenをプロキシに配置し、AIがアクセスできないようにする。AIはHTTP経由でGitHub APIを呼ぶだけである。
理屈は難しくなく、docker-composeでDevContainerを起動してサイドカーにNginxを使い
gh-proxy:
image: nginx:alpine
volumes:
- ./gh-proxy/default.conf.template:/etc/nginx/templates/default.conf.template:ro
environment:
GH_PAT: ${GITHUB_CLAUDECODE_KEY}
環境変数でPATをこのような設定を読み込ませるだけでも利用できる。なお、なるべくFine-grained personal access tokensを用い、強すぎる権限を付与しないこと。
ポイント
- gitは相対パス利用 : Git 2.48+の–relative-paths/worktree.useRelativePaths
- ホストとDevContainerそれぞれでgit操作をするため
- WorkTreeは/.worktrees/ 以下に作成
- /をDev Containerにマウントするため、よく見る同階層に配置する方式がとれない
ディレクトリ構成はこのようになる
<repository name>/
├─ .claude/
├─ .devcontainer/
├─ .git/
├─ src/
└─ .worktrees/
├─ feature-example/
└─ bugfix-example/
事前作業
worktree.useRelativePathsを有効化
git config worktree.useRelativePaths true
# useRelativePaths = true があるはず
cat .git/config
.worktrees/ を.gitignoreにいれておく。
ワークツリーの作成
新規のブランチを切る場合
git worktree add -b feature/example .worktrees/feature-example origin/main
すでにあるブランチを使う場合
git worktree add .worktrees/feature-example feature/example
Claude Codeの起動
作成したワークツリーまで移動した後でClaude Codeを立ち上げる。
cd .worktrees/feature-example
claude
ワークツリーの削除
git worktree remove .worktrees/feature-example
Why Dev Container?
- AIを隔離してセキュリティを維持（権限最小化）
- AIが閲覧できるのはマウントしたディレクトリだけ
- 利用できるツールやネットワークも限定
- GithubやAWSなどの権限もAI専用に
- 環境統一が容易
- 設定ファイルをリポジトリに保存しておけばワンクリックで環境再現
- たとえWindows/Mac混在チームでもDevContainerなら対応可能
- CI/CD(Linux)との環境統一も視野に入れられる
- エディタ連携もある
- Visual Studio Codeとの連携も便利
- VS ホスト起動
- AIがユーザーの権限を利用できてしまう。これは通常広すぎるし強すぎる
- e.g., 機密情報を含んだファイルが閲覧できる権限、データを消せる権限、AWSの重要リソースを停止・破壊できる権限など
- チーム間の環境統一も手間がかかる
- ホストのOS自体WindowsだったりMacだったり
- CI/CDとの連携も加えるとさらに難儀に
- ホスト環境も汚れるしセットアップも面倒
Setup
設定ファイルの保存場所
<Gitのルートリポジトリ>/.devcontainer/
単一コンテナ VS docker compose
- 開発のためミドルウェアなどの別コンテナが必要ならdocker-compose
- それ以外は単一コンテナで十分(YAGNIの精神)
- あとからdocker-compose対応にするのもAIを使えばさほど手間ではない
バージョン指定
- 環境統一のため、ベースイメージや主要ツールはバージョンを明記する
- 原則フルバージョン（X.Y.Z）を記載する
- マイナーバージョンまで（X.Y）でも可
- 固定ではなく指定。バージョンアップは積極的に
- latest運用は避ける
ベースイメージ管理
- ビルド済イメージを活用
- ゴールデンイメージを作って主要部分は確実に共通化
- 開発用とCI/CD用の違いはそれぞれのDockerfileで吸収
- 管理の手間がかかるため、これ自体も自動化
セキュリティ維持の取り組み
- AIエージェントは100%安全なシステムではない
- prompt injection、クラウドAIなら運営側の事故による漏洩などなど
- リスクマネジメントが必要
- 権限付与の基本は
短命トークン + 最小権限- ExpireなしのAPIキーは原則として利用させない
- AWSならIdentity Center + 妥当な範囲の権限 + Service control policies (SCPs)
- 妥当な範囲の権限 ≒ 機密情報を含まない範囲の読取権限 ＋ 最小限の更新権限
- 完璧主義で最小化を目指すと実用性が損なわれるため、「妥当な」権限縮小を
- 重要リソースの更新など責任を伴う業務は原則として人間を絡めることを推奨（ヒューマンインザループ）
- GitHubの
ghはExpireを短めにしたFine-grained PATで妥協（最短のExpireでも長いので期待しすぎないこと）- 権限管理の仕組みが今のところAWSほどうまくかみ合わせられない
- 読み取り禁止設定もやらないより良い
- これでは利用できないほど重要なリポジトリでは、DevContainer + AIでリポジトリごと預けるのを潔く避ける
- リポジトリ内の設定ファイル(e.g., .envなど)に機密情報を平文で保存しておかない
- たとえ動作設定でDenyしても閲覧されるリスクがゼロにはならない
- SSM Parameter Storeなど外部に出す
- リポジトリへの保存がどうしても必要なら暗号化する
- ただし、この場合AIが復号できてしまわないようにする
- 復号した後のファイルを放置してうっかりAIに読まれてしまわないようにもする
- 環境変数で受け渡す方式はリポジトリに保存しないで済むが、AIエージェント相手の隠ぺいとしては不徹底
- そもそも論、AIが関係なくともリポジトリに平文で機密情報を保存すべきでない
Claude Codeの動作設定
- 権限設定
- まず危険な内容をDeny
- 機密情報を含むファイルの閲覧(e.g.,
.env, ~/.aws/credentials) - 危険なコマンドの利用(e.g.,
sudo、rm -rf)
- 次に効率優先でよい内容をAllow
- コードを保存したディレクトリ(e.g.,
src/)でのファイル編集
- それ以外は手動確認
- ネットワーク設定
- 通常必要なドメインは許可
- 任意ドメインは禁止
- アタッカーのドメインにつなげられてしまうので
- もし任意ドメインの調査がしたいなら、リポジトリに紐づいたDev Containerを使わないで別のコンテナを使う
Why CI/CD?
- 手順実行の確実化
- 効率化
- 毎回人力で行うのは手間がかかる。特にビルドを挟むものや手順が多いものは威力大
- 自動化で効率よく
- 明確化
- 人力だと見えない手順が隠れていて暗黙知になることも
- 明文化で作業の透明性確保
- 誰が実行したかもしっかり記録（トレーサビリティ）
セキュリティ重視
- 乗っ取られると被害が大きい。対策はしっかりと
- 基本は最小権限の原則とアカウント管理
- 最小権限の原則
- 完璧主義でなくてもいい、ただしリスクを許容できる域まで落とす
- 管理者権限は以ての外
- アカウント管理
- CI/CDを編集できるアカウントはMFA必須
- 業務利用のCI/CDにID・Passwordだけでログインしているアカウントは関与させない
- APIキーもできる限り使わない
- GitHub Actionsはやや特殊。コード管理と権限管理を同時に行う
信頼性
- pre-buildコンテナの活用
- 高速化というメリットもあるが、外部リポジトリに依存しなくて済む点もメリット
- バージョンは極力指定する
- latest運用は思わぬ仕様変更で挙動が変わる恐れがある
- 脆弱性の問題もあるので定期的な更新は必要
- 手間はかかる
- 重要なものだけ。完璧主義は報われない
なにで組むか？
- 利便性重視でいいならGitHub Actions、セキュリティ優先ならAWS CodePipeline
- 便利なのはGitHub Actions
- GitHubとの連携が楽
- 開発者体験もいい
- コスパも悪くない
- 信頼できるメンバーで集まって小規模開発をするならこれでいい
- 一方セキュリティの穴を作らないように組むのはかなり気を遣う
- GitHubと一体な分、守るべき場所が多い
- アカウント管理もAWS IAM Identity Centerと比べると緩い
- ビジネスの根幹となってるインフラのIaCを任せるべきかは考えどころ
- IaCでCI/CDをやるなら強い権限を渡さざるを得ない
- 強すぎる権限を渡すと設定の穴を突かれた際に被害が大きい
- それなのに穴があきやすい
- 「設定を完璧にやれば問題ない」はその通りだが、何年も運用する間ずっと完璧でいられるかが問題
- セキュリティ優先ならAWS CodePipeline
- AWS・IaC・CI/CDで重要システムを構築するならこれが手堅い
- フロントエンドやバックエンド（データ操作系以外）はGHA、インフラやマイグレーション等はこちらという使い分けもあり
- アカウント管理は堅牢そのもの
- 「SCP(サービスコントロールポリシー)を使った権限制限」「MFA必須」様々な工夫がある
- 権限管理もGitHub Actionsよりさらに細かく設定可能
- ただし設定が手間
- AIのおかげでマシになったが、それでも設定には苦労する
- セキュリティに強いのと裏表だが権限設定はとても細かいので大変
- UXももっさり感ある
- 大昔と比べると遥かに良くなってはいるがGitHub Actionsほど手軽かと言われると辛い
- もっともGHAはその分セキュリティ面で泣き所がある
高速化
- ジョブの並列実行
- CPU数を確保できるインスタンスを利用しつつ、ジョブの中でも並列実行
- キャッシュも実行
- pre-buildコンテナの活用
- 必要なツールを先に入れておく
- 安定する、早い
- ただし管理が手間
- それでも重いビルドやテストはGitHub ActionsのSelf Hosted Runnerも手
CI/CDをあえて避けるケースも
- つまりはオーバーエンジニアリングを避ける
- 実験環境で作業効率優先の場合
- Try&Errorが多い場合はCI/CDを挟むと辛い
- GHAがコンテナを立ち上げている暇に、ローカルでちょろっとなおしたスクリプトをすぐsync
ブランチ戦略のポリシーについて述べる。具体的なブランチ戦略（e.g., Git Flow, GitHub Flow, etc)には踏み込まない。
ブランチ戦略の目的
コードの品質と本番環境の安定性を、開発フローの構造によって担保する。
- オペミスやAIの暴走によってコードの破壊や開発中のコードがリリースされるのを防ぐため、本番用のブランチを保護する
- 品質保証のため、本番への変更は必ずレビューとCIによる自動テストを経てから行う
- 後から追跡しやすいようブランチを用途によって区分する
また、これらは極力仕組みで保証し、個人の注意力に頼らないようにする。
ブランチ戦略とマージ戦略
なるべく独自戦略は避け、広く知られたブランチ戦略を用いる。実績に支えられた品質が期待できること、メンバーの学習コストを軽減できることが理由である。
どの戦略を用いるとしても、運用のブレを最小限に抑えられるよう、なるべくカスタマイズを避ける。
混乱防止のため、マージ戦略も同一のリポジトリでは単一のマージ戦略を用いる。その場その場で異なるマージ戦略を用いたり、あるいは複数のマージ戦略を混入させない。
命名規則
原則として採用したブランチ戦略の命名規則に従う。
命名規則は極力自動検証する（例：Git hook / CI）。
バージョン番号はセマンティックバージョニングで統一する（例: 1.2.0）。
仕組みによる強制
いずれのルールも仕組みによっておのずから守られるようにする。品質と保守性向上のため開発ルールは極力守られるべきであるが、人の注意力あるいはAIのプロンプト順守には100%を期待し得ない。これらの仕組みはGitHub Rulesetのような元から用意されている仕組みだけでなく、Git フックやGitHub Actionsのように後から追加できる仕組みを用いる。
例）
- GitHub Ruleset によるmainブランチの保護
- Gitフックによるコミットメッセージの整形
- GitHub Actionsによる自動テストの強制
緊急時・想定外のケースのため管理者が保護ルールをバイパスする仕組みは残しておく。ただし常時バイパスできる必要はなく、ブレイクグラス方式でもよい。
バイパスした際は、その理由を後で追えるよう理由を記録する（コメントでよい）
常にバイパスが必要になる運用は問題であるため是正する。
ルールの管理
属人性の防止・トレーサビリティの向上のため、保護ルールは極力IaCで管理し手動での設定変更を避ける。どうしても避けられない場合は記録を残す。
リリース方法
- オペレーション品質向上のため、リリースは人手を挟まずにCI/CDで完結させる。
- 逆に人手を介する運用（例：タグを切る際に担当者が元のコミットとバージョンを手入力する）は避ける。
AI利用の原則
- セーフティファースト
- 致命的な結果をもたらすような権限を決してAIに与えてはいけない
- e.g., 機密情報の流出、重要なデータの破壊などに繋がる権限は最初からすべてシャットアウト
- そのほかはリスクに応じた防御策を
- 情報の流出リスクをオプションや契約、保険契約で担保するなど
- 作業のリスクゼロを求めるとAI利用をあきらめるしかない。だがAI利用を避けること自体がビジネス上の巨大なリスクである
- 安全が確保されているからこそ積極的に利用できる。セキュリティは邪魔者ではない
- 十分なコンテキストの用意
- 必要な情報やツールへのアクセスが良好な生成の土台
- リスクを許容できる範囲内で上限いっぱいの権限を渡せるのが望ましい
- 精度に応じたプロンプトの作りこみ
- ちょっとした内容は思いついたままに聞けば十分。それでも今のAIなら十分な回答を返してくる
- 高い精度が必要な作業はコンテキストエンジニアリングやプロンプトエンジニアリングを考えるといい
- そしてできればプロンプトはSkillsなどの機能を使って使いまわす。何度もプロンプトを考えるのは大変なので
- さらにボリュームもあるならAIエージェントとSpec Drivenで対応
コンテキストエンジニアリング（プロンプトエンジニアリング含む）
- 生成に必要な情報を十分渡し、ノイズ情報を極力減らす
- 気づきづらいノイズ源は最小限に
- 自動挿入コンテキストに大量のノイズが含まれていることがある。そういうものを極力減らす。
- 例えばClaude CodeのCLAUDE.mdと履歴。
- 巨大すぎるプロンプトが必要になるなら、タスクを分割して小さくする
- 基本は「してほしいこと」と「してほしくないこと」そして厳密にやるなら「明確な受け入れ条件」
- スクリプトやツールで済むものはそちらを使う
- そのためのスクリプトやツールをAIに作らせればよい
- 指示を出す前に調査・確認する
- 雑な指示で生成させたところで全部捨てるはめになる。私はそれで何度も捨てた
- 公式MCP, 公式プラグインなどは積極的に利用を
- 渡したプロンプトの再現性・トレーサビリティを確保する
- なにも工夫しないとこうなる「もう一回同じ指示を出したくても出せない。なぜそうなったのかもわからない」
- これでは途中から生成させなおすことができない
- 生成されたものが指示通りか確認する術もない（指示が残ってないから）
- どこでどう確保するかは腕の見せ所
- リポジトリに保存、ログとしてのこす、Github Issueに残す、本当にいろいろある
開発体制の整備
- 開発ルールを整える
- 混乱防止: 混乱 -> e.g., リンターが複数ある、環境名がバラバラ、必要なテストが人によってあったりなかったりする、なんなら同じ人がやっててもそう
- AIの利用効率向上: 逐一指示しなくても「ルール通りにやれ」だけで済む
- 品質向上: 例えばフォーマッタ・リンター・静的解析の利用をルールで必須にするだけでも品質は底上げされる
- ワークフローも整える
- 型通りにやればすむことは型通りにやる。同じタスクは同じ手法で処理する。
- 都度都度やり方を考えるのは、それしかない時にやること
- 作業手順、書式のテンプレートなど行えることはたくさんある
- 自動化・仕組化する
- ルールを全部人間に守らせるのは大変。自動化・仕組化が望ましい
- 最たるものはCI/CD。フォーマッタのかけ忘れなどはありえなくなる
- 機械的に行えるのが一番確実だが、難しければAIにやらせる
- 確実性はやや劣る点にだけ注意すれば十分使い物になる
- 頻度が高い業務、ミスしやすい業務、認知負荷が高い業務はねらい目
- やりすぎ注意
- 整備にかかるコストと見返りを常に天秤にかけるべき。
- 2年に1度、30分で済む単純作業を1か月かけて自動化する合理的理由はない
Spec Driven
- そのメリットは 1)段階的な具体化による品質の担保 2)再現性 3)トレーサビリティ。デメリットは 1) 仕組みの構築が重い
- 対極と言える手法はVibe Coding。手軽だが品質はまちまちで、もう一度同じことをしたくても難しく、なぜそうなったのかわからない
- AI駆動開発やるなら必須の技術
- spec-kitがお手本
- ただし汎用性を追求している分、そのまま自分のプロジェクトに当てはめて使うのが難しい。実務にはカスタマイズして使うことを推奨
- 実運用は総合力勝負になる
- 開発体制の整備
- 要件定義、設計、作業指示書などのドキュメント作成能力
- 作成したドキュメントの管理能力
- チーム利用を前提とした改善サイクルと横展開
- AIエージェントの機能やCI/CDなどの自動化・仕組化
- 例えばIssueに要件を書き、その要件をClaude Codeに読ませて設計させてリポジトリに保存し、設計を元に作業指示書を作らせたあと実装する
- これをClaude CodeのSkillsやAgentsを使いながら行うことになる
- 仕組みの構築が重いので少しづつ充実させていくのが現実的
生成物の精度向上
- ポイントは「プロジェクトの頭で整え、末で保証する」
- してほしいことを形にするのがまず第一歩
- 要望が固まっていないと何が正解かも決まらない。変数の書き方一つとっても、スネークケースで書いて欲しいのかキャメルケースで書いて欲しいのかを決めてないなら、AIはどっちでも書いてくるし、どっちも正解になる
- 頭の中にあります、ではAIが参照できないので、形にする必要もある
- これは具体的には、要件や開発ルールなど形で現される
- 良好な生成をさせるための十分な情報を指示として渡す
- AI駆動開発も「システムの品質はテストの品質によって決まる」
- AIの生成はランダム。品質もランダム。AIにチェックさせても、チェック品質自体がランダム。 -> どれほどプロセス構築を頑張ってもこの品質のばらつきの壁を越えられず、プロダクト品質に届かない
- 信頼できるテスト（単体・統合・E2Eなど）で品質を保証するのが必須
- AIにテスト実行 → 結果を元にAIに修正させるループ
Githubの活用
- 権限管理をしっかり行い、安全を確保し、その上でAIに好きにさせる
- GitHubは権限管理をかなりきめ細かく行える
- Fine-grained personal access tokensだけでもかなり頑張れる。AI専用アカウントも用意できるとさらに柔軟な設定ができる
- 権限管理は自動化を強く推奨
- 確実に、素早く、漏れなく設定できる。
- Terraform, API, etc, etc.
- 基本的にモノレポ推奨
- Git本体はもちろん、Issue, PRも使うべき
ガバナンス
- ポリシーの文書化
- 使ってよい範囲を明示する
- 全てのリスクを会社が引き取るのは危険すぎる。しかし何も決めずに「何かあったら使った人間の責任」では業務で使えない。落としどころと責任分界を決めておく
- 使ってよいAIの範囲: 業務の性格によって決める。クラウドAIも可か？ 委託含め自社管理のAI(e.g., AWSのBedrock)までか？ 全面禁止か？
- 禁止事項の明示
- 国立標準技術研究所（NIST）の「AIリスクマネジメントフレームワーク」（AI RMF）が参考になる（邦訳版）
- 著作権やライセンス上の問題解決
- 妥当な権利帰属の取り決め: なにをどこまで保証するかの落としどころを決めておく。「“全"納品物の"全"著作権を譲渡する」のように過剰な条項はトラブルの元
- 生成物の商用利用・再利用: 規約で禁止されていないか確認が必要
- ライセンス汚染が問題となるOSSの利用: AIが勝手に使っていて気づかないリスクあり。スキャンを。
- コスト管理
- 雑に禁止せず運用による工夫を
- 機密情報とそうでもない情報が入り混じっていて分離もできないデータ群は、問題ない個所だけ別の場所に複製して使う
- 権限や安全性の面でAIに全面的にゆだねることができないが、しかしAIをできるだけ使いたいワークフローは、ヒューマンインザループで対応する
ナレッジ運用基盤
- 正確な情報を残す。そして検索できるようにする
- 作業記録は資産
- それをもとにAIに調べさせたり分析させたりするのに使う
- 人間にも有用
- チケットドリブン + バージョン管理システム + 再現性・トレーサビリティの文化で実現
- 楽なのはGithubとGithub IssueとPull Requestに作業を残すこと。CLIやAPI、権限管理の仕組みも充実しておりAIと組み合わせやすい
- 文化とは、やったことをちゃんと記録するのを善とする意識付け、またはAIに記録を義務付ける共通プロンプト(e.g., CLAUDE.md)
AIモデル選定
- AIモデル自体だけでなくAIエージェントの使い勝手も重要
- 今よく聞くのはClaude Code、Codex。次点でGemini CLIや自前でカスタムしたエージェント
- 定期評価もしたい
- 月一で同じタスクをそれぞれに投げてみる程度でも十分
- 評価・転換自体に多大なコストがかかる。頻繁な乗り換えは非合理的
組織的な展開
- 実際に使う。そして成果が出た仕組みを残す
- 最初に「AIの使い方をMECEで推定してそれに応じた仕組みを標準化し～」などと一から演繹するのは無理筋
- いわゆる過剰設計・オーバーエンジニアリングになる
- そもそも再現性がない・標準化のコストに見合わない小さな業務も多々ある。こういうタスクは標準化自体が向いてない
- 効果的なものは標準化・共有資産化する
- 使いまわせるテンプレートやワークフローも存在する。そういうものは標準化したほうがいい
- やりすぎないことが大事。標準化するコストは多大である。目的は品質の底上げと効率化であり、支配・統制ではない
- 継続的に改善もする
- .claude/もGitで管理してPR使いながら時折更新
- もちろん追加もしていい
- 成果物や利用率の指標は遅行指標としてのみ使うべき。KPI（ノルマ）にしてはならない
- AI活用の度合いは環境による影響が大きい。絶対評価に使うには雑過ぎる
TIPS
- 頻繁に使うコンテキストは英語化推奨
- 日本語よりトークン効率が良いので。
- 英語が苦痛でAIを使わなくなったら本末転倒なので、「出来れば」レベルの工夫
- 頻繁に使うコンテキストの代表はCLAUDE.md
