AI駆動開発工房

Policies

Monitoring

Policies

システムの監視ポリシーについて述べる。

監視の定義

あるべき状態が保たれていることを、適切な頻度で確認し続けること。そして保たれなくなったら検知すること。

  1. あるべき状態の例
    • サービスが動いている
    • SaaSの費用をちゃんと払っている。そして金額も妥当な範囲に収まっている
    • バッチが時間内に終わっている。途中で停止せず処理が最後まで行われている

-> どういう状態であってほしいのかから入る。手段からスタートしない。

  1. 適切な頻度で確認し続けることの例
    • DBの停止や再起動は起きたら即
    • WEBサービスの外形監視はN分おき
    • 指標のトレンド確認は週次でいいことがほとんど

-> 対応の緊急性に応じて合理的に設定。やりすぎはコストを増やす。

  1. 保たれなくなったら検知することの例
    • 緊急性の高いアラートはメールだけでなく電話も使って受け損ねを防止
    • 重要だが緊急ではないエラーのアラートは随時メール
    • 重要でも緊急でもないエラーはサマリーレポートを毎日決まった時間に確認

-> こちらも緊急性に応じて受ける方法を用意。監視漏れも監視疲れもよくない

なにを監視すべきか、すべきでないか

監視対象は、まずあるべき姿を洗い出し、そこからどう正常性を確認するのかを考えていく。あるべき姿はプロジェクトの性格によって異なるため、プロジェクトの性格に応じてカスタマイズする。監視内容によってはアプリケーションに可観測性のための機能を持たせる。どんなサービスでもこれだけやっておけば妥当と保証できるチートシートは元から存在しないのであり、手段から対象を決めるべきでない。

監視対象の違いの例)

また監視は対応とセットである。対応ノウハウの共有のため、可能なものは手順や判断基準をあらかじめドキュメント化しておく。それが難しいものは対応後に記録を残して関係者が（許されるならAIも）いつでも参照できるようにする。

ノイズアラートの防止

不要な監視は行わない。メンバーの疲弊やアラートの見落としを誘発するためである。 このため追加は本当に必要か検討した上で行う。一度追加してしまうと、実際はフォールスポジティブばかりで役に立たないアラートでさえ、責任問題となるリスクにより削除しづらくなる。

まず、アラートの発報を伴う監視は対応可能性とセットで考える。対応不要あるいは対応不能なことに発報すべきでない。

意味のあるアラートの例

意味のないアラートの例

具体例

ポリシーとしては上記のみであるが、理解の促進のためWEBアプリケーションを例にとって具体例を付け加える。

この場合、まずエンドユーザーつまり利用者にサービスが提供し続けられていること。ひっくり返すと、提供し続けられなくなるような事態になっていないこと（異常検知）、もしくはいずれ重大な障害が出ると予想されないこと（予兆検知）が必要である。この前提で、WEBアプリケーションで各レイヤごとに監視すると例えばこのようになる。

次にそのサービスを続けていけること。このために具体的にはセキュリティやコストを監視する。

また監視はアラートだけセットするのではなく、トレンドを見るためのメトリクスとそれをまとめたダッシュボードも用意する。問題の存在を告げるトレンドが出ていたら対応が必要である。例えばレイテンシが悪化していく一方であったり、メモリの残量が下がっていく一方であったりするなら、なんらかの不具合が隠れている可能性が高い。

一方で必要性の薄いアラート、有用性の低いアラートは流さない。

Log Management

Policies

ログ管理について述べる。

ログを管理する目的

ログは開発・運用に欠かせないものであるから、適切に収集と保管を行う。

ログの基本要件

ログは目的に応じ以下の要件を満たした状態で保存する。

取得するログは例えば下記のようなものがあげられる。

何を記録してはいけないか

セキュリティおよびコスト最適化の観点から、下記のようなログを記録してはならない。

いつまで保持するか

ログの保持期間は用途によって変更する。例えば下記のようにする。

必要以上に保持しないほうがコスト最適化のためにはよいが、必要になった際に消してしまっているほうが通常は問題が大きいため、余裕をもって設定する。

保持期間を過ぎたログは、速やかに削除または適切にアーカイブする。

セキュリティ

ログの保全のため、業務に必要なものに対してのみ操作権限を与える。例えば下記のようにする。

ログの保管場所

ログの保管はセキュリティが保て、かつ毀損しないよう十分な信頼性を持った手段で行う。例）AWS S3 ただし障害対応や監査対応に支障が出ない程度の時間で参照できること。

GitHub Access Security Tiers

Policies

さまざまな権限付与方式

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 AppGitHub Appが短命トークンを発行。それをAIが利用する短命高いありえるが悪用リスクは限定的
直接トークンPATをAIに直接付与長命高いありえる

※ 流出リスクについて: 上記はあくまでAIによる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 worktree

Policies

ポイント

ディレクトリ構成はこのようになる

<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

Dev Container

Policies

Why Dev Container?

Setup

設定ファイルの保存場所

単一コンテナ VS docker compose

バージョン指定

ベースイメージ管理

セキュリティ維持の取り組み

Claude Codeの動作設定

CI/CD

Policies

Why CI/CD?

セキュリティ重視

信頼性

なにで組むか？

高速化

CI/CDをあえて避けるケースも

Branching Strategy

Policies

ブランチ戦略のポリシーについて述べる。具体的なブランチ戦略（e.g., Git Flow, GitHub Flow, etc)には踏み込まない。

ブランチ戦略の目的

コードの品質と本番環境の安定性を、開発フローの構造によって担保する。

  1. オペミスやAIの暴走によってコードの破壊や開発中のコードがリリースされるのを防ぐため、本番用のブランチを保護する
  2. 品質保証のため、本番への変更は必ずレビューとCIによる自動テストを経てから行う
  3. 後から追跡しやすいようブランチを用途によって区分する

また、これらは極力仕組みで保証し、個人の注意力に頼らないようにする。

ブランチ戦略とマージ戦略

なるべく独自戦略は避け、広く知られたブランチ戦略を用いる。実績に支えられた品質が期待できること、メンバーの学習コストを軽減できることが理由である。

どの戦略を用いるとしても、運用のブレを最小限に抑えられるよう、なるべくカスタマイズを避ける。

混乱防止のため、マージ戦略も同一のリポジトリでは単一のマージ戦略を用いる。その場その場で異なるマージ戦略を用いたり、あるいは複数のマージ戦略を混入させない。

命名規則

原則として採用したブランチ戦略の命名規則に従う。

命名規則は極力自動検証する（例：Git hook / CI）。

バージョン番号はセマンティックバージョニングで統一する（例: 1.2.0）。

仕組みによる強制

いずれのルールも仕組みによっておのずから守られるようにする。品質と保守性向上のため開発ルールは極力守られるべきであるが、人の注意力あるいはAIのプロンプト順守には100%を期待し得ない。これらの仕組みはGitHub Rulesetのような元から用意されている仕組みだけでなく、Git フックやGitHub Actionsのように後から追加できる仕組みを用いる。

例）

緊急時・想定外のケースのため管理者が保護ルールをバイパスする仕組みは残しておく。ただし常時バイパスできる必要はなく、ブレイクグラス方式でもよい。

バイパスした際は、その理由を後で追えるよう理由を記録する（コメントでよい）

常にバイパスが必要になる運用は問題であるため是正する。

ルールの管理

属人性の防止・トレーサビリティの向上のため、保護ルールは極力IaCで管理し手動での設定変更を避ける。どうしても避けられない場合は記録を残す。

リリース方法

AI-Driven Development

Policies

AI利用の原則

  1. セーフティファースト
    • 致命的な結果をもたらすような権限を決してAIに与えてはいけない
      • e.g., 機密情報の流出、重要なデータの破壊などに繋がる権限は最初からすべてシャットアウト
    • そのほかはリスクに応じた防御策を
      • 情報の流出リスクをオプションや契約、保険契約で担保するなど
      • 作業のリスクゼロを求めるとAI利用をあきらめるしかない。だがAI利用を避けること自体がビジネス上の巨大なリスクである
    • 安全が確保されているからこそ積極的に利用できる。セキュリティは邪魔者ではない
  2. 十分なコンテキストの用意
    • 必要な情報やツールへのアクセスが良好な生成の土台
    • リスクを許容できる範囲内で上限いっぱいの権限を渡せるのが望ましい
  3. 精度に応じたプロンプトの作りこみ
    • ちょっとした内容は思いついたままに聞けば十分。それでも今のAIなら十分な回答を返してくる
    • 高い精度が必要な作業はコンテキストエンジニアリングやプロンプトエンジニアリングを考えるといい
      • そしてできればプロンプトはSkillsなどの機能を使って使いまわす。何度もプロンプトを考えるのは大変なので
      • さらにボリュームもあるならAIエージェントとSpec Drivenで対応

コンテキストエンジニアリング（プロンプトエンジニアリング含む）

開発体制の整備

Spec Driven

生成物の精度向上

Githubの活用

ガバナンス

ナレッジ運用基盤

AIモデル選定

組織的な展開

TIPS