AI DEVELOPMENT / OPERATIONS GUIDE
AI開発を、コード生成ではなく「変更を安全に届ける仕組み」として理解する
Git・GitHub、Pull Request、CIから、Agent Harness、状態管理、権限、独立QC、復旧まで。NetsujoがAI開発を実運用する中で得た知見を、ひとつの線で学べるように整理しました。
CURRENT STATE
今どこまで進んでいるかを読む
AUTHORITY
誰が何を実行できるかを分ける
EVIDENCE
何が確認できたかを版に結び付ける
01 / THE WHOLE FLOW
一つの変更が公開されるまでを、5段階に分ける
AI開発でも、人間の開発でも、実装・検証・公開は別の段階です。ここを一つの「完了」にすると、CI成功を本番成功と誤認したり、古い版のレビューを新しい版へ流用したりします。
01
依頼する
Issue
目的、制約、受入条件を明文化する。
02
変更をつくる
Commit / PR
変更を履歴として残し、レビュー可能な単位にする。
03
確かめる
CI / Review
対象の版を固定し、自動検証とレビューを分けて確認する。
04
公開する
Deploy
検証済みの成果物を対象環境へ反映する。
05
観測する
Monitoring
実際の画面・機能・利用時の状態を確認する。
判断基準
「コードを書いた」「PRを作った」「CIが通った」「mergeした」「本番で動いた」を、同じ意味の“完了”として扱わない。各段階に、対象と証拠を持たせます。
02 / OPERATING PRINCIPLES
Netsujoが実運用から固定した6つの原則
長いプロンプトで注意し続けるのではなく、再発した問題をRule、Test、CI、Gate、Evidenceへ移すための基準です。
実装・検証・公開・観測を、一つの「完了」にまとめない
CIが成功しても、merge・deploy・本番確認は別工程です。どこまで済んだかを別々の証拠で答えられる状態にします。
検証結果は、必ず対象の版へ結び付ける
同じPRでもHEADが変われば別の対象です。コミットIDと、その版に対するCI・レビュー・確認結果を対応付けます。
モデルの賢さと、実務を安全に進める仕組みを分ける
Model、Agent、Harnessは同じではありません。道具、文脈、停止条件、権限、観測、復旧は周辺の運用設計で決まります。
状態・権限・証拠を分けて管理する
誰が書けるか、今どこまで進んだか、何が確認できたかを分離すると、複数エージェントでも現在地を見失いにくくなります。
独立QCは、実装者の自己申告を置き換える
実装と検証を別の実行環境・文脈に分け、同じ対象IDを確認します。対象が変われば、以前のPASSはそのまま再利用しません。
結果が不明なら、再試行の前に現状を確認する
タイムアウトや応答停止は「未実行」を意味しません。二重送信や二重公開を避けるため、外部状態を照合してから再開します。
03 / THE STACK
用語ではなく、「何を管理する層か」で分ける
GitHubは履歴と共同作業の基盤、HarnessはAIの実行基盤です。Agent OS・Controller・Orchestratorは、Netsujoが責任を重複させないために置いている運用上の役割です。
Git / GitHub / Actions
履歴・共同作業・自動検証
Commit、Branch、PR、Review、CI、Deployの位置関係を理解し、変更と証拠を追跡できるようにします。
Agent Harness
AIを実行環境へつなぐ
Instructions、Tools、Context、実行ループ、Guardrails、Observability、Recoveryを束ねます。
Agent OS
Netsujoの運用規範
状態・権限・証拠をどう扱うかを共通ルールとして定めます。一般規格ではなく、Netsujoの運用上の定義です。
Controller
進行可否と実行権を管理
現在状態、writer、通過条件を管理し、BLOCKEDやOUTCOME_UNCERTAINを安易に「失敗」「完了」へ置き換えません。
Orchestrator
複数の実行を調整
担当割当、並列実行、復旧、独立検証を調整し、同じ対象への競合や重複作業を抑えます。
このガイド
学ぶための入口
AI開発・運用の概念と実務の流れを体系化する常設ハブ。
Agent OS
実運転の証拠
Netsujoが実際に使う制御基盤・運用設計と、その検証記録。
AI実務コミュニティ
継続共有の場
イベントや実践知を、人と人の間で継続的に共有する場。
※ Agent OS、Controller、Orchestratorの役割分担はNetsujoの運用上の定義です。業界共通の標準や、特定製品の公式名称として示しているものではありません。
04 / LEARNING PATH
今の課題から、読む順番を選ぶ
GitHubの基礎から、本番運用の統制までを一度に理解する必要はありません。現在の詰まり方に合わせて、必要な層から読めます。
LEVEL 1
まずGitHub上の「現在地」を読めるようにする
Branch、HEAD、base/head、PR、Checks、merge、deployを分けて理解する段階です。変更がどこにあり、何が検証されたかを読める状態を作ります。
LEVEL 2
AIを「道具」ではなく実行系として設計する
複数AIの役割、Harness、停止条件、状態保持、権限境界を設計します。モデル選定だけでは解けない問題が中心になります。
LEVEL 3
本番へ届けるための統制と復旧を組み込む
Controller、Orchestrator、Independent QC、Evidence、Gate、Recoveryを使い、速さではなく終端まで安全に到達できる運用へ移します。
05 / KNOWLEDGE MAP
既存記事を、時系列ではなく「解きたい問題」で読む
技術ブログのAI開発記事を、体系・状態統制・失敗学・実測・導入の5レーンへ再編しました。URLは変えず、各記事がこのマップへ戻る導線を持ちます。
FOUNDATION / EXECUTION
体系・実行基盤
AIを使うこと自体ではなく、仕様・役割・Tools・MCP・RAG・並列実行をどう組み立てるかを扱います。
5 ARTICLES
ChatGPTで設計し、Claude Codeで実装し、Codexで監査する
ChatGPTが設計、Claude Codeが実装、Codexが品質監査。AI分業を採用した理由と、全変更へ直列適用したときに生じた手戻り・トークン消費・ブランチ混乱、そしてリスク別品質ゲートへの再設計を公開します。
読むAIエージェントを並列で動かしても壊さない
Claude CodeやCodexを同一リポジトリで並列運用するとき、Git worktree、変更範囲、Task Contract、実行環境、マージ順序で競合と手戻りを抑える実務設計を解説します。
読むMCPで業務ツールをつなぐ
MCP(Model Context Protocol)でAIエージェントに業務ツールをつなぐ実装パターン。ツール設計の3原則・権限とサンドボックス・段階的導入まで。
読むRAGを業務で動かす
社内文書をLLMに接続するRAGの実装と運用の勘所。チャンク設計・ハイブリッド検索・出典提示・評価(evals)・アクセス権限とセキュリティまで。
読むClaude Code仕様駆動開発 — Markdownから本番デプロイまで
Netsujo仮想会社で実践するClaude Codeの仕様駆動開発を公開。Markdown仕様書を中核にSub-Agents・MCP・Hooks・Skillsで生成と評価を分離し、品質ゲートを通して本番デプロイまで回す手順と失敗事例。
読むSTATE / GOVERNANCE
状態・統制
状態、権限、Evidence、CI、レビュー、承認、Deploy、本番確認を分け、複数AIを安全に終端させるための知見です。
12 ARTICLES
CodexとClaude Codeを並列で動かして分かった。AIエージェント開発で本当に難しいのは『状態管理』だった
CodexとClaude Codeを並列運用して分かった、AI開発の本当の難所。チャットを正本にしない状態管理、single writer、Exact-head QC、OUTCOME_UNCERTAIN、restart safetyを実運用から整理します。
読むAI開発を半年回して分かった。ボトルネックはコードではなく「統制」だった
Claude Code 540セッション、merge済みPR 1,764件の実測から、実装量と事業成果を分離。失敗をテスト・CI・Hook・Evidence・停止条件へ変え、次に追うKPIを整理します。
読むAIエージェントの業務運用設計｜役割・権限・監査・停止条件
京都の少人数スタートアップNetsujoが、AIエージェント（Claude Code）と自動化、事実を担保する仕組みで品質を支える運用OSを公開。独立レビュー、CI、週次監査の設定と実行・通知の確認まで。
読むAIに二度同じ注意をしたら、それはプロンプトではなくシステムのバグである
ChatGPT・Claude Code・Codexとの実開発で、同じ注意を繰り返す監督労働をController、Evidence Ledger、Gateへ変換。同じ確認を人間に二度させないAIエージェント開発の統制設計を実体験から解説します。
読むAIエージェントはGitHub Actionsを使いすぎる｜CIを77.4%短縮した「発火設計」
AIエージェントでcommitとpushが増えた環境のCIを、Draft・Ready・Final Candidateと変更pathで再設計。docs-onlyの通常CIを9分31秒から2分09秒へ77.4%短縮した実測と、安全性を落とさない条件を公開します。
読むAIレビューの予算と停止条件を設計する
AIレビューを回数無制限で続けると、レビュー工程そのものが安心の儀式になります。レビュー対象、リスク分類、1差分あたりの予算、再レビュー条件、停止条件を実装から公開します。
読むAIエージェントのStopと外部processの停止を分ける
チャットのStopは会話の生成を止める操作であり、起動済みのworkflow、cron、deploy、migrationを止める操作ではありません。7状態で停止を扱い、観測の継続とrollbackを別操作として設計します。
読むPR番号ではなくExact SHAで検証対象を固定する
「CIはGREENです」という報告だけを根拠にmergeすると、検証したコードと操作した対象がずれます。PR_HEAD_SHAからPRODUCTION_SHAまで7つのSHAを別々に持ち、merge直前に同一性を再確認します。
読むCLOSEDはMERGEDではない—対策済みを5層で確かめる
Pull RequestがCLOSEDでもmergeされたとは限りません。PR state、mergedAt、main ancestry、意味的な取り込み、必要な挙動の存在という5層のEvidence ladderで「対策済み」を確かめます。
読むCIが落ちたら、rerunの前にfailure signatureを分類する
CIが赤くなるたびにrerunすると、直っていない失敗が緑で隠れます。failure evidenceを保存し、deterministic・flaky・infrastructure・rate-limit・unknownへ分類してから次を決めます。
読むDeployが成功しても本番は未確認｜Production verificationの分け方
デプロイworkflowの緑は、本番が期待どおり動いている証拠ではありません。main SHA、deploy input SHA、Production SHA、schema、公開経路と認証済み経路、browser evidenceを分けて確認します。
読むAIエージェントの承認設計をリスク区分で分ける方法
全Pull RequestにOwnerのexact-SHA認可を要求した結果、低リスク変更まで統合が止まりました。LOW/MEDIUMは自律統合、HIGHはexact-SHA認可と独立FINAL_QC、UNKNOWNはfail-closedへ分けます。
読むINCIDENT / FAILURE
失敗学
実際に起きた事故を、原因の説明で終わらせずRule、Policy、Gate、Regression Testへ変えた記録です。
3 ARTICLES
AIエージェント開発・運用の事故録
ChatGPT・Claude Code・Codex・GitHub Actionsの実運用で起きた引き継ぎ不全、CI誤判定、並列競合、本番検証漏れを、ルール・テスト・権限・Evidenceへ変えた全12回のシリーズです。
読む同じ案件なのに、チャット名が違う。問題は名前ではなく識別子だった
同じ案件のチャット名がツールごとに異なり、後継作業とPRの対応が追えなくなりました。名称完全一致を必須にして撤回した経緯と、WORK_ITEM_IDを安定識別子へ移した引き継ぎ契約を整理します。
読むAIエージェントによるSEO改善の誤実装
2026年4月にAIエージェント（Claude Code）で進めた自社サイトのSEO改善には、一般ページをGoogle Indexing APIへ送信するという誤りが含まれていました。何を撤回し、何を残し、再発防止にどの品質ゲートを置いたかを記録します。
読むEVIDENCE / EVOLUTION
実測・変遷
何セッション動かしたか、何が速くなったか、どこで人間の判断が残ったか。運用の変化を一次情報として残します。
3 ARTICLES
AIで会社は速くなった。経営者の時間は戻ったのか
約3か月のAI運用を、会社全体の処理能力と経営者自身の時間に分けて再評価。未計測のROIを盛らず、Founder AI Touch Timeなど次に追うKPIを整理します。
読むClaude Codeで1人4プロジェクト並行運用の記録
2026年3〜4月の1ヶ月でClaude Codeを用い1人で4プロジェクトを並行運用。435コミットの実戦ログから、Sub-Agent・Task・Memory・Skill・MCPの組み合わせ、レビューゲート設計、失敗と対処まで公開。
読むAIエージェント時代の一人開発と「判断の孤独」
AIエージェントによって実装速度は上がった一方、設計、優先順位、公開時期、耐えどきの判断は一人に集中します。Netsujo SIGNALの開発で得た教訓と、一人開発を破綻させない運用設計を整理します。
読むADOPTION / BUSINESS
導入・業務接続
自社業務へAIを入れるときの診断、RAGや業務ツール接続、相談・導入の入口を扱います。
2 ARTICLES
06 / FAQ
AI開発・運用でよく出る疑問
AIエージェント開発で最初に難しくなるのは何ですか？
モデルの生成能力より、誰が何を触っているか、どの版を検証したか、どこまで公開されたかを追う状態管理が先に難しくなります。AIを増やすほど、担当・権限・証拠・復旧の設計が重要になります。
Agent Harnessとは何ですか？
本ページでは、モデル呼び出しに加えて、Instructions、Tools、Context、実行ループ、Guardrails、Observability、Recoveryなど、AIを継続的に動かす周辺基盤をまとめてHarnessと呼んでいます。製品や組織によって範囲は異なります。
CIがGREENなら、そのまま本番へ出してよいですか？
いいえ。CIは所定の自動検証が通った証拠であり、merge、deploy、本番動作確認とは別です。検証対象SHA、必要なレビュー、反映先、本番確認を分けて確認します。
ControllerとOrchestratorは同じですか？
Netsujoでは分けています。Controllerは現在状態と進行可否・実行権を管理し、Orchestratorは複数の担当割当、並列実行、復旧、独立検証を調整します。これはNetsujoの運用上の役割分担です。
独立QCは、通常のコードレビューと何が違いますか？
実装者と異なる実行環境・文脈から、同じ対象IDを検証することを重視します。差分だけでなく、テスト、実画面、運用上のリスクまで確認し、対象が変われば再検証します。
このガイドとAgent OS、AI実務コミュニティはどう違いますか？
このガイドはAI開発・運用を体系的に学ぶ常設ハブ、Agent OSはNetsujoの実運転と制御設計の証拠、AI実務コミュニティはイベントや実践知を継続共有する場です。それぞれ役割を分け、相互に接続しています。
FROM KNOWLEDGE TO OPERATING SYSTEM
AIを導入するだけでなく、運用できる形へ落とす
PoCの受入条件、複数AIの役割分担、品質ゲート、権限分離、復旧、本番観測まで。Netsujo自身のAI開発運用で得た知見を、個別の業務・開発プロセスへ適用します。