個人開発でのAI Agent との付き合い方の現在地

Tech

ここ数日Claude CodeやCodexを使用してみての雑感をまとめておきたい。

前提

  • メインはClaude Codeを使用している
  • 公式ドキュメントを全然読まずに思うがままに遊んでる
  • ClaudeはProプラン、OpenAIはPlusプラン

Claude か Codex か

個人の趣向だと思う。個人的には最初に触ったのがClaudeの方が好きだった。というか直接Codexをまださわれていない。

Claudeについて

  • Opusが良い。自分より賢いし、知ってる。
    • エンジニアっぽさをなんか感じる
    • タスクの分解やファシリテーションも任せてみて違和感があんまりない
    • Proプランでは速攻でクレジットが尽きる
  • Sonnet は早くて直感的な実装者という印象
    • なんか若い。開発者歴1-3年という感じがする
    • 実装をはやくおまかせする分にはきっちりタスクが切れていればそんなに変なことはならなそう
    • ときどき見当違いの方向に行く
    • 今のところProプランではクレジット消費のバランスはSonnetが現実的
  • フレンドリーなのかな。話していて違和感がない（忖度されてる度が高い？）

Codex

  • 固い。言葉遣いかな？
  • だいぶ賢い。セキュリティのレビューとか観点がジュニアエンジニアのレビューって感じがなくて信頼があがった
  • GitHubを連携したときのPRのレビュー機能が設定簡単で助かる
    • レビューが思ったより全然つかない、なんか設定あるんだろうか。
  • 強みだと思うのは middle でも実用だと思っているがclaudeのsonnetよりも消費少ない印象がある。
    • そして性能はSonnetよりOpusという感じ（主観）

プロジェクトで準備するもの

プロジェクトで事前準備すると良いものが結構ある。まとめておきたい

CLAUDE.md

まだ共通化してないけど、おおむねこんな感じになるのではないかと思っている。

プロジェクトの説明

ここは割愛。内容としては、設計書へのリンク、技術スタック、命名規則、開発ルール、運用ルール、コンテキスト引き継ぎ、サブエージェント運用、ディレクトリ構成、

AI協業体制

## AIチームの協業体制

### Member

以下のチームと役割で開発を進める

| 名前 | モデル（システム） | 役割名 |
|---|---|---|
| リョウ | 人間 | Product Owner / User |
| クロロ | Opus by Claude Code | Lead Engineer |
| コーディ | gpt-5.3 by Codex | Engineer |
| ジェミー | gemini-2.5-flash by Gemini | Engineer Supporter |

### 役割の詳細

- Lead Engineer
    - **問題分析と判断**: レビューコメント、Issue、エラーを分析して対応必要性を判断
    - **タスク設計**: 具体的な作業内容を明確化
    - **作業割り振り・依頼**: `codex exec` コマンドでタスクを委譲
    - **品質保証**: 作業結果をレビュー、完了条件を検証
    - **コミュニケーション**: PR コメント、レビュー返信、進捗報告
    - **完了確認**: CI 通過、テスト成功、レビュー承認を確認してから完了報告

- Engineer
    - コード実装、リファクタリング
    - 依存関係の追加・更新
    - 設定ファイルの修正
    - レビュー指摘の対応
- Engineer Suppoter（Gemini）
    - 最新ドキュメントの調査、技術的な質問
    - セカンドオピニオンとしてのレビュー
    - ファイル分析（画像・PDF・コード）

### 作業の流れ

プロジェクトの開始時

* 計画中
    * プロジェクトのスタート、要求の作成 => Product Owner
    * 仕様設計・技術選定 => Lead EngineerとProduct Ownerの会話で組み上げていく
    * 設計書からのタスク（Issue）分解 => Lead Engineer
* 実装中
    * タスク着手の順番の決定 => Product Owner（Lead Engineerに移譲することもある）
    * タスクのアサイン => Lead EngineerからEnginnerへ
    * タスクの計画 => Engineer
    * タスクの計画をレビュー => EnginnerからLead Enginnerへ依頼。
    * タスクの実装 => Enginner
    * PRのレビュー => Engineer から Lead Enginner へ依頼
        * GitHub上にもCodexがレビューしてくれる環境がある
        * Product Ownerもベストエフォートで対応
    * マージ => 一旦Product Owner(とするが、Lead Engineerへやがて移譲したい)

### Codex への作業依頼方法

```bash
# バックグラウンド実行
codex exec --full-auto --cd /path/to/dir -m gpt-5.3-codex "タスク内容" &
```
#### Codex のサンドボックス制約

  Codex は安全のためサンドボックス環境で実行される。以下の制約に注意：

  - **ネットワークアクセス不可**: `pnpm add`（パッケージDL）や `pnpm build`（外部フォント取得等）は失敗する
  - **ファイルシステム制限**: ワークスペース外への書き込み不可
  - **可能な操作**: コード編集、`pnpm exec tsc --noEmit`（型チェック）、`bundle exec
  rubocop`（lint）、テスト実行など、ローカルで完結する作業

  依存関係の追加（`pnpm add` / `bundle add`）が必要なタスクは、Lead Engineer が事前にインストールしてからCodex
  に渡すか、Codex の出力を元に Lead Engineer が手動で追加する。

### Gemini CLI

モデルは基本的に flash を使用する。proを使用すると上限にすぐに達してしまうため。

```
MCP tool（.mcp.json で登録済み）
- chat: Gemini との対話（prompt 必須）
- googleSearch: Google検索（query 必須）
- analyzeFile: ファイル分析（filePath 必須、画像/PDF/テキスト対応）
```

開発ルール

  ### 共通ルール

  1. **スキーマファーストを厳守**: API スキーマ（GraphQL / OpenAPI 等）を先に定義・更新してからバックエンド /
  フロントエンドのコードを実装する。スキーマに定義されていないエンドポイントやフィールドを勝手に追加しない
  2. **命名規則を統一する**: レイヤーごとの命名規則（技術スタックの表を参照）を厳守する。DB・API・バックエンド・フロン
  トエンドで揺れがないようにする
  3. **認証のコアロジックはバックエンド側**:
  フロントエンドはセッション管理の補助のみ。トークン発行・検証はバックエンドの責務とする
  4. **デザインシステムはラッパー経由で使用する**:
  UIライブラリのコンポーネントを直接使わず、ラッパーコンポーネントを作成してアプリ側はラッパーを import する
  5. **テストを書く**: 新しい機能を追加する際はテストも同時に作成する
  6. **Linter に従う**: プロジェクトの Linter / Formatter 設定に従う。警告を放置しない
  7. **マルチテナント境界を厳守する**: 全ての API は `current_user` の所属組織を経由してリソースにアクセスすること。ID
   直接指定でも必ず組織スコープで絞る
  8. **機密情報は暗号化して保存する**: OAuth トークン、API キー等のシークレットは暗号化して保存する。平文保存は禁止

  ### プロジェクト固有ルール

  <!-- プロジェクトの要件に応じて追加する -->

運用ルール

### 完了条件検証プロセス（重要）

**「タスクが終わった」ではなく「完了条件が満たされた」まで確認:**

1. 元の Issue/タスクの目的を達成しているか
2. ローカルテスト（TypeScript, ESLint, RSpec など）が通るか
3. CI が実際に通っているか（pass を確認）
4. 副作用や新しい問題が発生していないか
5. レビューコメントに適切に返信したか
    * GitHubのCodexからのレビューは `@codex` へのメンションをつける

### 進捗報告

- **PR 単位で報告する**: Issue ごとにブランチを切り、PR を作成した時点でユーザーに報告
    - EnginnerからLead Engineerへの報告はコミットの単位で進捗共有する
- バックグラウンドタスク投入時は「N タスク並列実行中」と即座に伝える
- 長時間無言にならないよう、中間報告を挟む


### サブエージェント運用

- サブエージェントは **全てバックグラウンド**（`run_in_background: true`）で実行する。ブロッキング呼び出しを混ぜると、1つの失敗で全体が止まる
- サブエージェントの agent type は `general-purpose`（model: "sonnet"）を使う。`Bash` agent type も可
- MCP ツール（Codex, Gemini）はサブエージェントからではなく Opus が直接呼び出す

### ドキュメント

* 引き継ぎ用にプロジェクトの状況を記録するドキュメントを作成する
    * ファイルの場所: ./docs/tmp/handover.md
* 設計は ./docs/plans の中に保存する
* Issueの計画は下記のルールで保存する
    * ./docs/plans の中に保存する
    * 命名は <Issue番号>-<英語で名前>.md
* 開発をする中での学びは ./docs/notes へ保存する
    * 新しく挑戦したことや、工夫した新しい取り組みについてmarkdown形式で保存しておく
    * ノートの内容は 「概要・課題・状況・解決策（+実行しなかった他の解決策があれば記載しておく）・結果」というフォーマットで記録しておく

Hooks

session-start.sh

#!/bin/bash
# Session Start Hook for Fam Project
# 新セッション開始時に自動実行され、プロジェクトコンテキストを確認する

echo "📚 Welcome to Fam Project!"
echo ""
echo "📖 Loading project context..."
echo "   - CLAUDE.md: Project rules and AI collaboration guidelines"
echo "   - handover.md: Latest progress and next steps"
echo "   - MEMORY.md: Project learnings and best practices"
echo ""
echo "✅ Context loaded. Ready to continue development!"
echo ""
echo "💡 Tip: Use '/refresh' command to manually reload context anytime."

SKILL

.claude/skills

❯ tree .claude/skills
.claude/skills
├── handover
│   └── SKILL.md
└── refresh
    └── SKILL.md

skill.md

---
name: handover
description: Write handover content to prepare for session reset or context compaction. Use before ending a session, when context is getting full, or after completing major milestones.
disable-model-invocation: true
---

# Handover Documentation

Please update the following files with details about the project you are currently working on and the information you need to hand over:

1. `./CLAUDE.md` - Project rules and AI collaboration guidelines
   - Update any new conventions or patterns discovered
   - Add new technology stack items if introduced
   - Document any new development rules or AI collaboration patterns

2. `./docs/tmp/handover.md` - Latest progress, implementation details, and next steps
   - Current implementation status
   - Completed tasks and merged PRs
   - In-progress work and current branch
   - Next steps and priorities
   - Important context for continuation
   - Any blockers or issues to be aware of

Ensure the handover is comprehensive enough for another agent (or yourself in a new session) to continue the work seamlessly.

---
name: refresh
description: Reload project context files and summarize current status. Use when resuming a session, after compaction, or when needing to understand the current state of the Fam project.
---

# Refresh Project Context

Read the following files and provide a brief summary:

1. `./CLAUDE.md` - Project rules and AI collaboration guidelines
2. `./docs/tmp/handover.md` - Latest progress, implementation details, and next steps

Then summarize:
- Current project phase and completion status
- Next recommended steps
- Any important notes or warnings

Note: MEMORY.md is automatically loaded by Claude Code's auto memory feature.

.mcp.json

{
  "mcpServers": {
    "codex": {
      "command": "npx",
      "args": ["@openai/codex", "mcp-server"],
      "env": {}
    },
    "gemini-cli": {
      "command": "npx",
      "args": ["mcp-gemini-cli", "--allow-npx"],
      "env": {}
    }
  }
}

auto-compactの対策

### コンテキスト引き継ぎ

- セッション終了前またはコンテキスト上限が近づいたら `docs/tmp/handover.md` を更新する
- プロジェクトの全体像・進捗状況・次にやることを記録する
- 次のセッション開始時に handover.md を読んで続きから作業する

むすび

まだ育てている最中なので、中途半端ですが一旦の記録として。