AIエージェント運用設計
フォルダとセッションの「境界」を整える

なぜ「境界」を設計するのか

AIエージェントの運用でつまずくとき、原因はプロンプト単体よりも作業場の切り方にあることが多い。同じように頼んでいるのに成果が安定しない、前回の続きから始めたら意図した文脈がない、複数の作業が混ざって判断がぶれる——これらは成果物の境界と会話の目的境界がずれているサインだ。

Claude Code はその構造が特に分かりやすい。セッションをディレクトリ単位で保持し、CLAUDE.md を読み込み、並列作業は分離された作業場所を前提にしている。つまりツール側の設計が最初から「境界ありき」で作られている。これはコードに限らず、文章・調査・資料づくりでも同じだ。

ここで整理したいのは、成果物の境界（人に見せる・共有する・あとで直す単位）と、目的の境界（1回の会話で一貫して追える作業意図）だ。リベシティ投稿1本、講座資料1本、家計分析1本、Webアプリ1本がそれぞれ1フォルダ。情報収集・構成づくり・清書・確認がそれぞれ1セッション。この二層を揃えると、再開・相談・やり直し・並列作業が扱いやすくなる。

成果物設計の原則——1成果物=1フォルダ

原則はシンプルだ。人に見せる・共有する・あとで直す単位を1フォルダに閉じる。リベシティ投稿1本、講座資料1本、家計分析1本、Webアプリ1本、調査レポート1本——それぞれが独立した葉フォルダになる。

このとき重要なのは、共通メモを厚くしすぎないことだ。プロフィール、文体、禁止事項のように全テーマで使うものは薄く置く。一方で、家計相談の前提、講座資料の対象者、記事の主張、アプリの仕様は成果物ごとのメモに閉じる。関係ない前提をAIへ渡しすぎないためだ。

また、複数成果物をまたぐ会話は例外運用にしたほうがいい。「投稿Aと講座Bをまとめて整えて」よりも、「投稿Aの構成」「講座Bの導入」のように分ける。横断比較や移行計画のような「調整セッション」だけ例外にするのが無難だ。

推奨ディレクトリ構成と命名規則

迷ったら、トップレベルを 用途分類で固定し、その下を成果物の葉フォルダで増やす。分類を増やし始めると今度は人間が迷うので、まずは writing/・research/・life/・apps/・sandbox/ くらいから始める。

~/workspace/
├── writing/
│   ├── libecity-ai-agent-post/
│   │   ├── CLAUDE.md          ← 読者・文体・主張
│   │   ├── outline.md
│   │   └── draft.md
│   └── seminar-money-basics/
│       ├── CLAUDE.md
│       ├── slides-outline.md
│       └── handout.md
├── research/
│   └── ai-agent-session-study/
│       ├── CLAUDE.md
│       ├── questions.md
│       └── findings.md
├── life/
│   └── household-review-2026/
│       ├── CLAUDE.md
│       ├── expenses.csv
│       └── notes.md
├── apps/
│   ├── billing-admin/
│   │   ├── CLAUDE.md
│   │   ├── .claude/
│   │   │   ├── settings.json
│   │   │   ├── rules/
│   │   │   │   ├── testing.md
│   │   │   │   └── security.md
│   │   │   └── skills/
│   │   │       └── release/
│   │   │           └── SKILL.md
│   │   ├── src/
│   │   └── tests/
│   └── mobile-auth-poc/
└── sandbox/
    └── throwaway-2026-04-30/
        ├── NOTES.md
        └── tmp/

分類の意味はシンプルだ。writing/ は投稿・記事・講座資料、research/ は調査記録、life/ は家計・暮らし・学習ログ、apps/ はアプリやサイト、sandbox/ は破棄前提の実験。Claude Code はコード以外のフォルダでも問題なく動くので、文章や調査を無理にコードリポジトリに押し込む必要はない。

推奨命名規則

セッション名は、後から見て「何の会話だったか」が分かる名前にする。Claude Code なら -n や /rename で付けられる。ChatGPT や Claude でも会話タイトルを整えておくと再開が楽になる。main、temp、test2 のような曖昧な名前は避ける。

会話・セッションの標準ライフサイクル

1本の長い会話より、短い目的別セッションの連鎖が強い。文脈は増えるほど便利になる一方で、無関係な情報が混在するほどAIの判断はぼやける。ライフサイクルを「調査→構成→作成→確認」に分けることで、各フェーズが新しい文脈で始まる。

特に重要なのは、構成を作ったら、新しい会話で作成に入るパターンだ。投稿なら「論点出し」と「本文作成」を分ける。講座資料なら「対象者整理」と「スライド作成」を分ける。開発なら「仕様化」と「実装」を分ける。別セッションで確認すると、直前の流れに引っ張られにくくなり、品質が上がりやすい。

コマンドと並列作業の使い分け

Claude Code のセッション操作コマンド

並列開発は worktree 付きマルチセッションで

開発で複数の修正を同時に試すなら、第一選択は worktree 付きマルチセッションだ。Claude Code は --worktree と Git worktree の両方を前提にしており、デスクトップ版も各並列セッションを独自の Git worktree に置く。

# worktree を切って新しいセッションを開始する
git worktree add ../billing-admin-auth-fix -b fix/auth-fix
cd ../billing-admin-auth-fix
claude -n billing-auth-fix

.env など Git で追跡されないファイルは .worktreeinclude でコピーできる。

# .worktreeinclude
.env
.env.local
config/secrets.json

AI運用アンチパターン集

ここまでの原則を、実際によく起きる失敗に落とすとこうなる。名前を付けておくと、「いまキッチンシンクになってるね」のようにチームやコミュニティでも共有しやすい。

共通メモのテンプレートと移行計画

共通メモに書くべきなのは毎回再説明したくない事実だ。誰に向けた成果物か、何を大事にするか、使ってよい材料、避けたい表現、確認方法。Claude Code ではこれを CLAUDE.md に置ける。通常チャットでも、会話の最初に同じ情報を短く貼るだけで効く。

非エンジニア向け：最小メモ

# Outcome
- リベシティ向けの投稿を1本作る
- 読者: AI活用に興味はあるが、開発経験はない人
- 完成条件: 3分で読めて、今日から1つ試せる

# Tone
- 専門用語は使いすぎない
- 断定しすぎず、実体験ベースで書く
- 煽りよりも、落ち着いた実践知を優先する

# Materials
- 自分の体験メモ
- 参考記事URL
- 投稿したい結論

# Check
- 読者が最初に何をすればよいか分かるか
- 具体例が1つ以上あるか
- 個人情報や未確認情報が混ざっていないか

開発向け：最小実用版 CLAUDE.md

# Project overview
- Outcome: billing-admin web app
- Primary user: internal ops team
- Definition of done: lint green, affected tests green, PR-ready diff

# Tech stack
- TypeScript 5 / Node.js 22 / Next.js 15
- PostgreSQL + Prisma
- Vitest / Playwright

# Important directories
- src/app/        routes
- src/features/   domain features
- src/shared/     shared UI and utilities
- tests/          integration and e2e tests

# Common commands
- Install: pnpm install
- Dev: pnpm dev
- Typecheck: pnpm typecheck
- Lint: pnpm lint
- Test: pnpm test
- Build: pnpm build

# Rules
- Prefer existing patterns in src/features before adding abstractions.
- Do not edit generated files under src/generated/.
- Before finishing, run typecheck + affected tests + lint.
- Keep changes PR-sized. If scope grows, stop and propose a split.

# Compact Instructions
- Preserve changed files, failing tests, pending TODOs.
- Never drop required env vars or review comments to address.

散らかった環境からの移行フェーズ

一度に全部直そうとしない。まずは境界を先に切り直す。設定の作り込みは、その後でいい。

個人運用とコミュニティ運用の違い

個人運用とコミュニティ・チーム運用の差は、共有すべきものをどこに置くかに集約される。リベシティ内で誰かと一緒に投稿、講座、イベント、ツールを作るなら、AIへの頼み方も共有知識として扱ったほうがいい。

日々の運用チェックリスト