Web 開発・Codex・AI・運用

最終更新: 2026-08-01

技術の目的

個人開発の技術戦略は、最先端構成を作ることではなく、少人数で次を満たすこと。

顧客価値を短い周期で変更できる
誤りをリリース前に検出できる
事故の影響範囲を制限できる
障害を観測し、戻し、復旧できる
顧客数が増えても創業者の手作業が比例しない
ベンダー、モデル、価格変更に交換可能な境界がある
セキュリティ、プライバシー、課金の証拠を残せる

AI がコード量を増やせるほど、仕様、テスト、型、権限、計測、レビューが希少になる。

既定のアーキテクチャ

初期は「モジュール化されたモノリス + 管理サービス」を既定値にする。

Web / mobile-friendly UI
        ↓
同一コードベースのアプリケーション層
        ├── PostgreSQL 等の関係 DB
        ├── オブジェクトストレージ
        ├── 認証・決済・メール
        ├── 非同期ジョブ / キュー
        ├── AI / 外部 API アダプター
        └── ログ・メトリクス・トレース・エラー監視

モノリスは無秩序を意味しない。ドメイン境界、依存方向、公開インターフェースを分ける。マイクロサービスは、独立スケール、障害隔離、異なる規制境界、別チームによる独立配備が現実の制約になってから検討する。

なぜ「退屈な技術」を選ぶか

ドキュメント、事例、ライブラリ、AI 学習量が多い
障害時に調べやすい
ホスティングと人材の選択肢が広い
Codex が生成したコードを人間がレビューしやすい
移行より顧客問題へ時間を使える

新技術は、明確な顧客価値、原価、制約を解く場合だけ導入する。

スタック選定

特定ベンダーより判断軸を固定する。

領域	判断軸
言語	型、安全性、既存経験、ライブラリ、AI/ツール支援
Web	SSR/SEO、フォーム、認証、キャッシュ、デプロイ、テスト
DB	トランザクション、制約、バックアップ、移行、検索
ホスティング	リージョン、コールドスタート、上限、ログ、移行性
認証	MFA、パスキー、組織、招待、監査、データ移行
決済	対象国、税、請求書、サブスク状態、返金、不正
AI	品質、構造化出力、ツール、価格、レート、データ条件
可観測性	エラー、トレース、ログ、メトリクス、アラート、費用

TypeScript は 2025 年の GitHub Octoverse で月間コントリビューター数首位となり、Web フロントからサーバーまで型を共有しやすい。有力な既定値ではあるが、既存の Python 資産、データ処理、運用経験が強ければ無理に統一しない。GitHub Octoverse 2025

個人開発向けの現実的な既定

1 リポジトリ
1 主要言語、必要なら AI/データ処理だけ別ランタイム
1 関係 DB
1 デプロイ方法
開発・プレビュー・本番の 3 環境
外部サービスは成熟した認証、決済、メール、ストレージから利用
非同期処理はキューまたは管理ジョブ
Infrastructure as Code は再構築・監査に必要な範囲から

「無料枠が多い」だけでサービスを分散すると、請求、資格情報、障害、データ所在、終了手順の負債が増える。

ドメインとデータ設計

画面より状態遷移を先にする

重要な業務を状態機械として書く。

下書き → 受付済み → 処理中 → 要確認 → 承認済み → 配信済み
                       ↓失敗      ↓却下
                    再試行待ち   修正待ち

各遷移に定義する。

実行できる役割
前提条件
副作用
冪等性キー
監査イベント
失敗時の状態
取消し・補償操作

AI の自由文に業務状態を持たせず、アプリケーションの決定的なコードと DB 制約を正とする。

DB 制約を使う

外部キー
NOT NULL
UNIQUE
CHECK
トランザクション
楽観/悲観ロックを必要箇所だけ

アプリ側検証だけでは、並行処理、バグ、手動操作、AI 生成コードから不正状態が入る。

識別子と時刻

外部公開 ID と内部 ID の推測可能性を検討
時刻は UTC 保存、表示で利用者タイムゾーンへ
金額は浮動小数でなく最小通貨単位または decimal
監査用 created_at、updated_at、actor、source
論理削除が必要か、法的削除と混同しない
スキーマ変更とデータ移行を別手順として検証

マルチテナント

初期でも他社データ混入は致命的。すべての顧客所有データにテナント境界を明示する。

サーバー側で認証・認可
クエリへ tenant_id を必須化する設計
可能なら DB の Row Level Security を追加防御として使う
キャッシュ、検索、オブジェクトキー、ジョブにもテナントを含める
管理者の代理操作を監査
テナント間アクセスの負のテスト
エクスポート・削除もテナント境界で検証

RLS だけ、UI の非表示だけ、推測困難 ID だけに依存しない。

認証と認可

認証は「誰か」、認可は「何をしてよいか」。ログイン済みだから操作可能とは限らない。

最低限:

成熟した認証基盤または十分に検証されたライブラリ
MFA/パスキーを高権限と重要顧客へ
セッション失効、端末・パスワード変更時の扱い
CSRF、Cookie 属性、リダイレクト URL の検証
招待、役割変更、退職、組織移動
所有者が最後の管理者を消す場合の処理
権限表とサーバー側のテスト
サポート担当のアクセスと監査

役割 × 資源 × 操作 × 条件

の表を作る。isAdmin の一変数で複雑な B2B 権限を表さない。

課金

課金は Webhook を受けるだけの機能ではなく、契約状態機械。

典型状態:

trialing / active / past_due / paused / canceled / unpaid

実装原則:

決済事業者を金銭取引の正とするが、製品権限への写像を自社で定義
Webhook 署名を検証
イベント ID で冪等化
到着順が前後する前提で最新状態を再取得
失敗時に再試行可能
権限付与・停止を監査
日割り、税、通貨、返金、チャージバックをテスト
顧客ポータルまたは同等の自己管理
解約後の利用期限・データ保持を明示
本番とテストのキー・商品 ID を分離

「支払成功画面へ戻った」だけで権限を付与しない。ブラウザを閉じても正しく収束するよう、サーバー側イベントと照合する。

Billing テスト表

新規月額/年額
無料試用の開始、成功、失敗、試用中解約
3D Secure 等の追加認証
更新成功、決済失敗、回復
上位/下位プランと日割り
数量・利用量変更
即時/期末解約、再開
全額/一部返金
Webhook 重複、遅延、逆順
税率・通貨・請求書

外部 API・Webhook・非同期ジョブ

タイムアウト、再試行、冪等性

ネットワークは失敗し、応答がなくても相手側だけ成功する。

接続・処理タイムアウト
指数バックオフ + jitter
再試行可能なエラーだけ再試行
最大回数と dead-letter queue
副作用操作に idempotency key
サーキットブレーカーまたは縮退
手動再実行と監査

無制限再試行は障害と請求を増幅する。

At-least-once を前提にする

多くのキューと Webhook は重複する。「一度だけ届く」を仮定せず、同じ入力が複数回実行されても最終状態と課金が正しくなるようにする。

外部 API 境界

domain service
  ↓ 自社の小さい interface
provider adapter A / B

ベンダー固有型をドメイン全体へ漏らさない。料金、制限、利用規約、障害時の代替を ADR または依存台帳へ残す。

ファイルとユーザー入力

MIME、拡張子、実体を検証
サイズ、ページ数、解凍後サイズ、処理時間を制限
マルウェア検査が必要な用途を判断
署名付き URL と短い有効期限
公開/非公開を明示
ファイル名をパスに直接使わない
画像・文書のメタデータに個人情報がないか
OCR・抽出結果を原文へ結び付ける
保存期間と削除ジョブ
不正ファイルで AI・パーサーが長時間動かない予算

メール

取引メールとマーケティングを分ける
SPF、DKIM、DMARC
バウンス、苦情、配信停止
メール内リンクの有効期限と再利用
宛先混入を防ぐテナント・テンプレートテスト
大量送信はキューとレート制限
本文・添付へ秘密や不要な個人情報を含めない
ローカル/プレビュー環境から実顧客へ送らない安全装置

API 設計

入出力スキーマとバージョン
認証、認可、テナント境界
ページネーション、フィルタ、並び順
レート制限と利用枠
エラーコード、再試行可能性、request ID
idempotency key
後方互換性と廃止期間
Webhook 署名、再送、イベントスキーマ
個人情報を URL、ログ、エラーメッセージへ入れない

AI に直接 DB 操作や任意 HTTP を許す代わりに、目的が狭い型付きツールを用意する。

テスト戦略

テスト数ではなく、事業リスクを覆う。

1. 決定的な単体テスト

金額、日付、権限、状態遷移
入力検証
課金権限の写像
AI 出力後の決定的な検証

2. 統合テスト

DB 制約とトランザクション
認証・認可
テナント境界
キュー・Webhook の重複と逆順
外部 API アダプター

3. E2E

収益・信頼に直結する少数の流れ。

登録/招待/ログイン
コア価値イベント
課金/解約
データ出力/削除
高権限操作

4. 非機能

アクセシビリティ
性能
セキュリティ
バックアップ復旧
障害注入・縮退
AI 評価

テストデータ

実顧客データを開発へコピーしない
境界、空、巨大、Unicode、タイムゾーン、通貨
複数テナントと複数役割
外部 API 失敗、遅延、重複
AI の誤形式、拒否、幻覚、プロンプト注入

CI/CD

PR ごとのゲート

フォーマット、lint
型検査
単体・統合テスト
依存関係・秘密・静的セキュリティ検査
DB マイグレーション検証
重要 UI の E2E とアクセシビリティ
ビルド
変更差分のレビュー

全てを重くして待ち時間を増やさず、速い必須ゲートと夜間/定期の深い検査に分ける。

デプロイ

不変な成果物を環境へ昇格
マイグレーションは後方互換な expand → migrate → contract
機能フラグで影響範囲を制限
少数顧客/内部から段階展開
リリース注釈をメトリクスへ記録
自動/手動ロールバック手順
ロールバックできないデータ変更は事前バックアップと補償処理

デリバリー性能の 5 指標

DORA の現行指標は、throughput を Change lead time、Deployment frequency、Failed deployment recovery time の 3 つ、instability を Change fail rate、Deployment rework rate の 2 つで捉える。他社の速度を目標値にせず、同じサービスの推移を見て、待ち時間、失敗、手戻りのどこが詰まっているかを改善する。DORA software delivery performance metrics

Change lead time: 変更の開始から本番稼働まで
Deployment frequency: 本番へ変更を届ける頻度
Failed deployment recovery time: 失敗した変更から回復するまで
Change fail rate: デプロイのうち障害・ロールバック・修正を要した割合
Deployment rework rate: 意図した価値提供でなく、本番変更の手直しに費やした割合

Preview 環境

便利だが、本番データ・本番メール・本番決済・本番 OAuth を誤用しない。短命 URL のアクセス制御、秘密、検索インデックス除外、削除を管理する。

可観測性

可観測性は、未知の問題を外部出力から調べられる能力。OpenTelemetry は traces、metrics、logs を生成・収集・出力するベンダー中立の仕組みで、監視バックエンドそのものではない。OpenTelemetry overview

最初に計測するもの

事業:

コア価値イベント
課金状態と売上
顧客別利用量・変動費
解約・返金

ユーザー体験:

成功率
p50/p95/p99 待ち時間
エラー、再試行、離脱
LCP/INP/CLS

システム:

リクエスト率、エラー率、レイテンシ
DB 接続、遅いクエリ、キュー滞留
外部 API のエラー・レート制限
ジョブ失敗、dead letter
デプロイ、設定変更

AI:

モデル、プロンプト/ワークフローバージョン
トークン、キャッシュ、ツール呼出し、原価
成功、拒否、形式エラー、再試行
評価スコア、人間修正、苦情

ログ規則

構造化ログ
request/trace ID
tenant/user は生値でなく必要最小限の識別子
パスワード、トークン、決済情報、全文個人データを記録しない
ログレベルと保存期間
顧客が送った AI 入力を既定で丸ごと残さない
エラーの利用者表示と内部詳細を分ける

SLI・SLO・エラーバジェット

Google SRE は、利用者が気にする挙動から SLI を選び、SLO を具体的な測定条件とともに定義し、100% を目標にせず許容失敗をエラーバジェットとして扱うことを勧める。Google SRE: Service Level Objectives

終端到達、業務成功、データ品質を一つの「成功」へ混ぜない。個人アプリの SLI 例:

過去 28 日間に受け付けた有効なレポート生成ジョブのうち、
10 分以内に正しい完了状態へ到達した割合。

成功不能と判定された有効なジョブのうち、
10 分以内に明示的な失敗状態へ終端した割合。

課金済み顧客の対象ダッシュボード表示のうち、
定義済みの整合性検査を通り、データ鮮度が 15 分以内だった割合。

各 SLI に母集団、除外条件、計測点、欠測の扱いを定義する。稼働率だけでなく、正しい結果、期限、重要ユーザージャーニーを測る。エラーバジェットを使い切ったら、新機能より原因除去・復旧性へ時間を移す。

アラート

人が行動できる条件だけ通知する。

顧客価値イベントの成功率低下
課金 Webhook 滞留
テナント境界または認証異常
AI 原価の急増
キュー最古メッセージ年齢
バックアップ失敗
SLO の急速な消費

全エラーを即時通知すると警報疲れになる。緊急、営業時間内、週次レビューへ分け、各アラートに runbook と所有者を付ける。

バックアップと復旧

バックアップが「成功」と表示されても復元できるとは限らない。

RPO: どこまでのデータ損失を許容するか
RTO: 何時間で復旧するか
DB、オブジェクト、設定、秘密、DNS、外部サービスを含む
別障害ドメイン・暗号化・アクセス制御
定期的な復元テスト
復元後の整合性、課金、Webhook 再処理
顧客ごとのエクスポート・削除との整合
サービス終了時のデータ返却

少なくとも四半期に 1 回、空の環境へ復元し、手順と所要時間を記録する。重要度に応じ頻度を上げる。

インシデント対応

手順

検知時刻、影響、暫定責任者を記録
被害拡大を止める: フラグ停止、キー失効、ロールバック、隔離
証拠を保全し、推測と事実を分ける
顧客影響と法的通知要否を評価
回避策と復旧見込みを簡潔に伝える
データ・課金・権限の整合性を確認して復旧
再発防止をコード、テスト、監視、手順へ反映

ポストモーテム

個人でも自責ではなくシステム改善を記録する。

タイムライン
顧客影響
検知経路
直接原因と寄与条件
うまく働いた防御
なぜ影響が広がったか
恒久対策、担当、期限、検証
AGENTS.md、テスト、runbook の更新

サポートと不正利用対応

サポート運営

サポートを無制限の善意作業にしない。契約・料金ページに、窓口、対応時間、対象範囲、目標応答時間、緊急連絡条件を示し、応答目標と解決時間の保証を分ける。

P0: 漏えい、他テナントアクセス、誤課金、全体停止。インシデント対応へ移す
P1: コア業務が停止し、回避策がない
P2: 回避策がある不具合、個別データ修正
P3: 質問、設定支援、機能要望

チケットには顧客、対象資源、発生時刻、期待結果、実結果、影響、再現、ログ ID、次回連絡時刻を持つ。メール変更、返金、データ出力、権限変更、代理操作の前に本人・権限を確認し、操作を監査する。

週次で、顧客当たりサポート時間、初回応答、再オープン、返金・苦情、上位原因を確認する。同じ質問は文書・UX へ、同じ事故はテスト・監視・runbook へ戻す。

不正利用

公開投稿、UGC、ファイル、API、メール送信、決済、AI ツールを提供する場合は、通常の侵入対策とは別に、正規アカウントの悪用を想定する。

登録、送信、生成、購入、公開のレート・件数・金額上限
異常な複数アカウント、決済、送信先、ツール実行の検知
通報、ブロック、緊急停止、証拠保全
コンテンツ非公開化、アカウント制限、異議申立て
誤検知と正当利用への影響の計測
高影響な永久停止・外部通報は人間確認

扱わない不正利用領域は利用規約だけでなく、製品機能と権限でも禁止する。

性能

Core Web Vitals の「良好」目安は実ユーザー 75 パーセンタイルで LCP ≤ 2.5 秒、INP ≤ 200ms、CLS ≤ 0.1。web.dev

実務原則:

先に実ユーザーを測る
DB と外部 API の p95 を追う
N+1、過剰取得、不要 JS、画像、フォントを確認
CDN とキャッシュに一貫した失効規則
大きい処理を非同期化
AI ストリーミングは体感を改善しても、誤った途中結果の扱いを設計
性能予算を CI とリリースレビューに置く

AI 機能を作るかの判断

AI を使う前に決定的な基準線を考える。

AI が向く:

非構造文書、画像、音声を扱う
言語の揺らぎが大きい
複数の正解があり、人が品質を判断できる
誤りを検出・修正できる
結果の価値が推論費を上回る

通常コードが向く:

金額、権限、請求、期限の確定計算
明確なルールと完全性が必要
同じ入力へ同じ出力が必要
誤りが即重大損害になる
小さな正規表現・SQL・ルールで十分

多くの良い製品は「決定的なワークフロー + 限定された AI 補助」である。

AI アプリの基本構成

OpenAI の公式 AI application development track は、コアロジックと評価を基礎とし、構造化出力・ツール呼出し、eval、guardrail、コスト・遅延最適化を本番化の要素に置く。OpenAI: AI app development

OpenAI 固有の新規実装では Responses API を基準にする。2026 年 8 月 1 日現在、Assistants API は 2026 年 8 月 26 日、Agent Builder と OpenAI Evals platform/API は同年 11 月 30 日に終了予定であるため、依存台帳と移行期限を持つ。「評価（eval）」という開発手法は引き続き必要であり、終了予定の Evals 製品とは区別する。Responses API への移行 / OpenAI API deprecations

入力
→ サイズ・権限・安全性検証
→ 必要情報の取得
→ モデル呼出し（構造化出力）
→ スキーマ・業務ルール検証
→ 人間承認または限定ツール実行
→ 結果・出典・状態を保存
→ 評価・フィードバック・原価を記録

モデルを境界の後ろへ置く

interface TaskModel {
  run(input, context, budget): TypedResult
}

ドメインがベンダーの response 型、モデル名、プロンプト文字列へ依存しないようにする。モデル・プロンプト・検索・ツールのバージョンを記録する。

構造化出力

自由文をパースして課金・権限・外部更新へ使わない。

JSON schema
enum、範囲、必須項目
追加プロパティ制限
スキーマ検証後に業務検証
不正時は安全に失敗
利用者向け文章だけを自由文にする

構造が正しくても内容は誤り得る。型検証は事実検証ではない。

Retrieval / RAG

文書所有権とテナント境界
取得元、版、更新日、権限
チャンクだけでなく原文へリンク
検索の recall/precision を評価
古い・矛盾した文書の扱い
外部文書を命令でなく非信頼データとして扱う
取得できなければ「不明」とする

知識を追加したいなら検索、振る舞いを安定させたいならプロンプト・評価・必要に応じ fine-tuning と役割を分ける。

AI 評価駆動開発

本章は実装・リリース品質を正本とする。offline eval、trace、tool effect、本番 job outcome を顧客価値・人手・provider 請求・更新へ接続する事業運用は 12 章で扱う。モデルの正答率だけを、価値率や単位採算へ読み替えない。

評価セット

評価データは、反復改善に使う開発セット、変更中は見ない固定 holdout、攻撃セット、本番から無作為またはリスク基準で採る新規監査標本に分ける。セット間の漏えい・重複と、主観評価における判定者間一致を管理する。

最初から巨大データセットは不要。20〜50 件の代表例を、評価設計を始める seed regression set として作る。これは低頻度の重大事故や本番分布に対する誤り率の統計的保証ではない。用途、言語、顧客、リスクで層化し、held-out set と本番由来ケースを継続追加する。リリース判定には件数、分子・分母、重大度別失敗、必要なら信頼区間を併記する。OpenAI Evaluation best practices

通常例
境界例
過去の本番失敗
悪意ある入力・プロンプト注入
不十分な情報
多言語・長文・壊れた形式
重要顧客の例外

各例に次を持つ。

入力 / 文脈
期待する性質または正解
許容される変動
禁止される結果
評価方法
重要度
由来と利用許諾

評価の層

決定的検査: schema、数値、引用、禁止語、ツール引数
参照正解: 分類、抽出、計算
ルーブリック: 完全性、関連性、根拠、文体
モデル評価: 一貫した rubric と校正
人間評価: 高リスク、微妙な品質、顧客固有
オンライン: 修正、再生成、採用、苦情、業務成果

モデルによる採点は人間の真実ではない。人間との一致を定期確認し、採点モデル変更もバージョン管理する。

リリースゲート

重要失敗率が基準を超えない
既存セットで回帰しない
十分な標本での p95 遅延・p90/p99 原価、または少数標本時の最大実績・負荷試験が予算内
セキュリティ・権限テストを通る
新モデルは少量カナリア
ロールバック可能

「新モデルのベンチマークが高い」だけで本番を置換しない。

AI エージェントとツール

エージェントは便利だが、長い自律ループは失敗・原価・権限を複合する。

最小権限

読取と書込ツールを分ける
目的ごとに狭いツール
入力 schema とサーバー側認可
許可リスト、対象上限、金額上限
最大ステップ、時間、トークン、費用
未信頼入力に基づく、または対象・影響範囲が確定していない外部送信、削除、公開、購入は都度の人間承認
事前承認済みの低リスク操作だけを、対象・金額・件数の上限、取消し、監査を備えて自動化
sandbox または隔離環境
全ツール呼出しを監査

OWASP の 2025 LLM Top 10 は Prompt Injection、Sensitive Information Disclosure、Improper Output Handling、Excessive Agency、Unbounded Consumption などを扱う。システムプロンプトを秘密保管庫と思わず、外部入力を命令として信用せず、出力を検証し、権限と消費量を制限する。OWASP Top 10 for LLM Applications 2025

OWASP Top 10 for Agentic Applications 2026 は、agent identity・権限の悪用、tool/MCP の supply chain、永続 memory の poisoning、agent 間通信、連鎖障害、人間と agent 間の信頼悪用まで対象を広げる。OWASP Top 10 for Agentic Applications 2026

ツール実行には短命な agent identity とサーバー側認可を使う
MCP/tool の出所と版を固定し、権限差分をレビューする
memory/RAG に provenance、テナント分離、失効・削除、poisoning テストを持つ
agent 間通信で送信者、scope、schema、nonce/replay を検証する
連鎖実行に深さ、件数、時間、費用、失敗伝播の上限を置く
承認画面にはモデルの要約だけでなく、サーバーが算出した対象、金額、権限、差分を示す

Human in the loop

人間承認は最後の防御であり、認可の代替ではない。単なる「OK」ボタンにしない。

変更前後の差分
対象、影響、費用
根拠と未確認箇所
承認者の権限
部分承認・修正
取消し可能性
高頻度で形骸化しない閾値

低リスクで十分評価できた操作だけを段階的に自動化する。

AI コスト・遅延

route 最適化の前後は、同じ eligible-job cohort で品質、安全性、全 retry/fallback、planned review、correction、founder rescue を比較する。価格表の effective version、usage component、invoice reconciliation を含む原価台帳は 12 章へ接続する。

タスクを単純/複雑へ分類しモデルをルーティング
共通で長い prefix はキャッシュを活用
文脈を必要最小限にし、検索品質を上げる
独立処理は並列、依存処理は順序保証
非即時は batch/flex 等の低コスト処理を検討
再試行前に原因を分類
同じジョブの重複実行を防ぐ
利用者に利用枠・待ち時間を予測可能に示す
品質を落とす最適化は eval で検出

原価を下げるためにモデルを替える前に、不要呼出し、長すぎる文脈、無制限ループ、低いキャッシュ率を直す。

Codex を中心にした開発システム

OpenAI の Codex best practices は、プロンプトに Goal、Context、Constraints、Done when を含め、複雑な作業は先に計画し、AGENTS.md に永続的なリポジトリ規則・実行・検証方法を置き、テスト・レビューまで行うことを勧める。Codex best practices

本節は技術原則の正本である。一件の変更について task、ADR、脅威、eval、PR、exact SHA、release、rollback、本番観測を結ぶ実行系とコピー用書式は 13 章を使う。

Codex の安全な実行基準

Codex では sandbox が技術的に許される操作範囲を、approval policy がどの操作で人の確認を要するかを制御する。両者は別の防御層である。ローカルではネットワーク無効、workspace 内だけ書込可能、必要時承認を安全な出発点にする。Agent approvals & security

未知・未信頼のリポジトリは read-only から開始する
通常は workspace-write と on-request approval を維持し、danger-full-access と never の組合せを常用しない
ネットワークは必要な作業だけ有効化し、可能なら宛先を許可リストへ絞る
Web、Issue、README、依存パッケージの説明、ツール出力を非信頼データとして扱う
本番秘密を agent が読める環境へ置かず、短命・用途限定の資格情報を使う
subagent は親の sandbox/approval を継承するため、委譲を権限分離と考えない
hook、plugin、MCP は出所と内容を確認し、リポジトリ側の CI・認可と別に管理する

1. 1 タスク 1 成果

Goal:
  顧客に見える変更または修正

Context:
  関連ファイル、設計判断、再現手順、ログ

Constraints:
  互換性、セキュリティ、変更禁止範囲、性能、法務

Done when:
  挙動、テスト、型、lint、レビュー、ドキュメント、計測

「アプリを改善して」より、「請求失敗後に権限を即時停止せず 7 日の回復期間を与え、Webhook 重複・逆順テストを通す」の方が検証可能。

2. AGENTS.md

短く、実行可能にする。

# Repository guide

## Layout
- `src/domain`: pure business rules
- `src/adapters`: external providers
- `tests/e2e`: revenue-critical journeys

## Commands
- Install: `...`
- Dev: `...`
- Test: `...`
- Typecheck: `...`
- Lint: `...`
- E2E: `...`

## Rules
- All tenant-owned queries require tenant scope.
- Never log credentials, prompts containing customer data, or payment data.
- Payment and permission changes must be idempotent and audited.
- Do not change public APIs or migrations without an explicit plan.

## Done
- Relevant tests added and passing.
- Failure, loading, empty, and permission states covered.
- Diff reviewed for security, privacy, cost, and rollback.

本書の運用ヒューリスティックとして、同種の誤りが反復したら、長い説教ではなく、規則、テスト、lint、hook のどこで機械的に防ぐかを更新する。AGENTS.md は正確で短い方がよい。Official AGENTS.md guide

3. 計画と ADR

複雑・曖昧・不可逆な作業は Plan mode または計画文書で、前提、選択肢、移行、検証、ロールバックを決める。重要な設計判断は ADR に残す。

Context / Decision / Alternatives / Consequences / Revisit when

4. サブエージェント

公式ガイドは、探索、テスト、ログ解析など独立した読取中心の作業をサブエージェントへ分け、主スレッドを要件・判断・統合に集中させることを勧める。複数エージェントが同じファイルを編集すると競合が増えるため、書込作業は境界または worktree で分離する。Codex subagents

向く分割:

コードベース探索
セキュリティレビュー
テスト設計と失敗解析
ドキュメント・規約調査
UI/アクセシビリティ監査

向かない分割:

同じコアファイルを同時編集
前提を頻繁に共有する小タスク
1 人なら数分の変更

5. Worktree

並列の書込や背景作業は Git worktree で checkout と変更差分を分離する。ただし worktree はセキュリティ境界ではなく、ホスト、Git メタデータ、資格情報、ネットワーク、ローカル DB、外部サービスを隔離しない。未知のリポジトリや危険なコード実行には Codex sandbox、短命なコンテナ/VM、テスト用資格情報、ネットワーク制限を併用する。マージ前に差分、テスト、マイグレーション、秘密を確認する。Codex worktrees / Codex sandboxing

6. Skills と自動化

同じ手順を繰り返すなら skill に、安定してから scheduled task にする。候補:

リリース前チェック
依存更新と変更リスク要約
失敗ジョブ・ログのトリアージ
週次 KPI と原価の要約
アクセシビリティ・性能監査
バックアップ復元リマインド
顧客フィードバックの分類

自動化前に通常タスクで数回成功させ、権限を最小にし、結果をレビュー可能にする。Codex scheduled tasks

7. Hooks と CI

Codex hook は秘密検査、追加検証、終了時レビューなどの機械的ルールに使えるが、信頼したスクリプトだけを実行する。最終的な共有規則は CI・リポジトリ側でも強制し、個人のエージェント設定だけに依存しない。Codex hooks

8. 生成コードの受入れ

Codex が「完了」と言ったことではなく、次で受け入れる。

変更を自分の言葉で説明できる
差分が意図した範囲
失敗ケースと境界テスト
権限、テナント、秘密、個人情報
原価と無制限ループ
DB 移行とロールバック
可観測性
依存関係とライセンス
実環境に近い動作確認

AI コードは junior/senior のラベルで信用せず、検証可能な成果物として扱う。

Codex delivery kitには、この受入基準を変更単位の証拠へ落とす root/nested AGENTS.md、task、ADR、threat、eval、PR、release、incident 書式がある。

セキュア開発の基準

OWASP Top 10:2025 は Broken Access Control、Security Misconfiguration、Software Supply Chain Failures、Cryptographic Failures、Injection、Insecure Design、Authentication Failures、Software or Data Integrity Failures、Security Logging and Alerting Failures、Mishandling of Exceptional Conditions を主要リスクとしている。OWASP Top 10:2025

Top 10 はリスク啓発の入口であり、受入れ検証の網羅基準ではない。Web アプリの具体的な検証要件には OWASP ASVS 5.0 を使い、機能ごとに対象レベルと証跡を決める。OWASP ASVS

NIST SSDF は、組織準備、ソフトウェア保護、安全なソフトウェア生成、脆弱性対応という結果志向の実践を開発ライフサイクルへ統合する枠組みを提供する。NIST SSDF

生成 AI/model を開発・利用・調達する場合は、SSDF の GenAI profile である NIST SP 800-218A も確認する。NIST SP 800-218A

個人開発では、セキュリティ・法務章のチェックをリスクに合わせて段階導入する。

リリース準備チェック

顧客価値

コア価値イベントを本番相当データで完了
空、失敗、処理中、権限不足、取消し
計測が事業成果につながる

データ・権限

テナント間負のテスト
サーバー側認可
収集・保存・削除・出力
ログに秘密・不要な個人情報なし

課金

署名、冪等、逆順、失敗回復
解約・返金・プラン変更
利用枠と AI 原価上限

運用

エラー監視、主要メトリクス、行動可能なアラート
SLO と runbook
バックアップと復元確認
ロールバックまたは停止フラグ
サポート・ステータス・インシデント連絡

品質

型、lint、テスト、E2E
アクセシビリティと実ユーザー性能
依存関係、秘密、セキュリティ検査
AI eval、prompt injection、過剰権限、原価
差分レビュー

事業継続

ベンダー障害・価格改定・終了時の代替
ドメイン、DNS、メール、決済、クラウドの MFA と回復手段
重要手順を自分以外でも読める
サービス終了時の顧客データ返却

速く作ることと、速く学ぶことは違う。技術上の完成条件は、コードが動くだけでなく、顧客価値を測れ、誤りを止められ、事故から戻せることである。

このチェックを exact commit、artifact、実行結果、出荷判断へ固定する場合は 13 章の release recordを使う。