環境差はエージェントの自律実行を妨げる。エージェントは人間の確認を挟まず実行するため、破壊的な操作や機密の漏洩をそのまま通しかねない。 前者は Nix Flakes で macOS / Linux のツールチェーンを宣言的に統一して解消する。後者は Issue駆動のロール分離と、機密の隔離・操作の制限で抑える。
AIエージェントの自律的な編集能力を活かしつつ、その実行が人間の確認を経ないままメインブランチや本番に及ばないよう、「設計・実装・検証」を分離したIssue駆動型開発フローを採用。
人間、対話型AI、自律型AIエージェントの各強みに応じて担当範囲を厳格に定義。
- WebChat (設計・対話型AI): ユーザーと対話しながら仕様策定および設計ファイルの作成を行う。検証手順は記述しない。
- AI Agent (実装・自律型AI):
作成されたIssueファイルをインプットとしてコード編集、静的エラー確認、PR作成までを自律実行。
rebuild等の破壊的コマンドや機密へのアクセスは.claude/settings.jsonの deny で構造的に遮断する。 - User (検証・人間): エージェントが作成したPRの検証手順に従い、動作確認とメインブランチへのマージを担当。
自律型エージェントにコード作成やテスト実行を任せるためには、動作させるローカルマシンの状態依存（環境差）を排除することが不可欠。
本リポジトリでは Nix Flakes および Home Manager をベースのインフラとして採用。MacBook（macOS）と Linux デスクトップにわたり、エージェントが利用するツールチェーン（Neovim, Yazi, Git, LSP等）や実行バイナリ、環境変数をコードとして同一化する。これにより、環境の差異によるエージェントの「コマンド未検出」「実行時エラー」を防ぐ。この同一性は CI（nix flake check）で継続的に検証している。
公開リポジトリ側のコードやIssueファイルに、本番環境のIPやポート番号、実ホスト名などの具体的な機密情報（シークレット）を直接記述しないよう、ローカルの secrets-agents/ ディレクトリに設計値を隔離してエージェントに参照させる。
起動するAIエージェントの実行環境の特性に応じて、ブランチ管理と指示ファイルを最適化。詳しいワークフローの挙動は docs-agents/issue-driven-workflow.md を参照。
| エージェント | 実行環境 | ブランチ管理 | 永続指示ファイル |
|---|---|---|---|
| Claude Code | ローカルマシン環境 | ローカルブランチを自動生成・操作 | CLAUDE.md |
| Jules | クラウド上のサンドボックス | ローカルブランチは生成せずリモート完結 | AGENTS.md |
Zshに統合された以下のシェルマクロ群により、チケット管理からエージェント起動、マージ後の後片付けまでをキーボード駆動でシームレスに処理。
issue-init/jules-init(環境初期化): 開発リポジトリをAI協調開発用に初期化。共通コンテキストディレクトリの生成、および対象エージェント用の指示ファイル（CLAUDE.md/AGENTS.md）を自動配備。issue/jules(チケット起動):status: open状態のIssueファイルをfzfでプレビューしながら選択。- Codeの場合: 自動で専用ローカルブランチ
claude/{id}-{slug}を作成・チェックアウトし、Claude CLI を起動。 - Julesの場合: ローカルブランチは作らず、直接クラウド上のセッションへタスクを投入。
- Codeの場合: 自動で専用ローカルブランチ
issue-abort/jules-abort(開発中断): 現在進行中のエージェントタスクを中断し、編集途中の状態をクリアしてメインブランチへ安全に復帰。issue-finish/jules-finish(PRマージとクローズ): 作成されたPRをghで検索・選択し、自動的にメインブランチへマージ。ローカルおよびリモートの作業ブランチをクリーンアップし、対象のローカルIssueファイルをstatus: closeに書き換え、メインブランチへ自動的にプッシュ。skill(Claude Code Skill ランチャー): dotfiles の.claude/skills/内の手動実行用スキル（SKILL.md の frontmatter にmanual: trueを持つもの）をfzfで一覧・プレビューし、選択したスキルをclaude /{skill-name}で起動。
エージェントと人間が同一環境で作業を行うための、Nixで一元化されたTUI（Text User Interface）環境。
- Neovim (IDE & Editor):
lazy.nvimをベースにした高度にモジュール化された統合開発環境。LSPによる自動補完や静的型チェック、自動コード整形（conform.nvim）、Yaziとのシームレスな統合のほか、Oil.nvimによるバッファ型ファイル操作、フローティングターミナル（ToggleTerm）、そして自動セッション復元などを備え、開発効率を最大化。 - Yazi (Terminal File Manager): Rust製の超高速ファイラー。fzf/ripgrep連携による高速検索や、終了時にシェルのカレントディレクトリを同期するラッパー関数を搭載。
- Tmux (Terminal Multiplexer): プレフィックスキー不要のペイン切り替え・分割、OSC 52による透過的なクリップボード同期、True Color対応など、リモート・ローカルの差異を埋める設定。Neovimの分割ウィンドウと同一のショートカット（Alt + 矢印、Alt + /、Alt + -、Alt + x）でシームレスに操作可能。
詳細なキーバインドや構成については、TUI Environment (docs/tui_environment.md) を参照してください。
新規リポで AI Agent 協調開発を始めるためのガイド群。5ファイルをセットで AI に渡し、標準的な開発環境を構築する。
| ガイド | 役割 |
|---|---|
| issue-driven-workflow.md | プロセス層。Issue 起点の開発フロー・担当分離・シェル関数 |
| harness-guide.md | ハーネス層。.claude/ 構成・settings.json・指示ファイル・検証手段 |
| cicd-guide.md | CI/CD 層。GitHub Actions・自動デプロイ・Cloudflare Tunnel |
| readme-guide.md | README の書き方。構成・言語規則・JUDGE.md 統合 |
| repo-guide.md | リポジトリ構成・機密管理・公開前チェックリスト |