0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@fuji1009_REBELL(Fujisawa Yuta)

Claude Codeで「AI秘書」を構築する全手順 — CLAUDE.md設計からマルチエージェントまで

0
Last updated at Posted at 2026-07-18

以前、Claude Codeの上に「AI秘書」を自作した話を実装Tips集として書きました。今回はその上位互換です。Tipsのつまみ食いではなく、同じシステムをゼロから組み上げるときに私が辿る手順を、構築順に通しで書きます。

対象読者は「Claude Codeは使っているが、タスク管理・委任・承認まで含む常設のエージェント構成を組みたい」人です。使うのは Markdown・シェルスクリプト・Claude Code標準機能（CLAUDE.md / サブエージェント / hooks）だけ。外部SaaSもDBも使いません。題材はすべて私の環境で実際に動いている構成です。動いていないものは書きません。

手順0: 完成形を先に見る

最終的に作るのは、リポジトリを1つの「会社」に見立てた次の構成です。

project/
├── CLAUDE.md                    # 薄い受付。起動手順とグローバル制約のみ
├── .claude/
│   ├── settings.json            # hooks の配線
│   └── hooks/kill-switch.sh     # キルスイッチ（PreToolUse）
├── agents/
│   ├── secretary-agent.md       # 秘書: ルーティングと判断ルールの本体
│   ├── cto-agent.md             # 部門エージェント（cto/cmo/cfo/legal/...）
│   └── cmo/writer-agent.md      # 部門配下の特化エージェント（2段目）
├── skills/                      # 再利用スキル
└── .company/                    # 状態はすべてMarkdown＝gitが履歴
    ├── approval-queue.md        # 承認キュー
    └── secretary/
        ├── tasks.md             # タスク台帳
        ├── projects.md          # プロジェクト台帳
        ├── handoff.md           # セッションをまたぐ作業記憶
        ├── audit-log.md         # 監査ログ
        └── PAUSED               # 置いたら全停止（普段は存在しない）

役割分担は3層です。CLAUDE.md＝憲法（毎回必ず読まれる最小限）、agents/＝人格と判断ルール（必要なものだけ読む）、.company/＝状態（毎回書き換わる）。この分離が以降の全手順の土台になります。

手順1: CLAUDE.md を「薄い受付」として書く

最初に書くのは CLAUDE.md ですが、ここにはほぼ何も書かないのが正解です。書くのは3つだけ。

  1. 起動手順（どのファイルをどの順で読むか）
  2. グローバル制約（キルスイッチ・承認必須の原則など、全員が守る憲法）
  3. 所有権マップ（どのルールがどのファイルにあるかのパス一覧）

私の環境の起動手順は、ほぼこの3行です。

## Session Boot Sequence
1. Read `agents/secretary-agent.md` — ペルソナと判断ルールを適用
2. Read `.company/secretary/handoff.md` — 前回の作業記憶を復元
3. Check `.company/secretary/PAUSED` — 存在すれば休暇モード（read-only）

逆に、口調・ルーティング表・部門ごとの業務ルールは CLAUDE.md に書きません。書いた場合に何が起きるか（肥大化→指示の無視）は別記事にまとめたので、ここでは結論だけ。CLAUDE.mdは索引と憲法、本体は外です。

手順2: 秘書の「人格書」を書く — 中核は Decision Rule

次に agents/secretary-agent.md を書きます。ここがシステムの本体です。窓口を秘書1人に絞る理由は単純で、判断ルールを1ファイルに集約できるからです。部門エージェントを何人増やしても、「何を自動でやり、何を人間に聞くか」の判定は秘書だけが持ちます。

中核は Decision Rule、依頼を受けるたびに上から評価する判定の順序です。

## Decision Rule — リクエストごとに、この順で評価する
0. キルスイッチ: PAUSED が存在 → 何もしない。read-onlyの報告のみ
1. ドライラン: DRY_RUN 中 → 「やるつもりの内容」だけ出力
2. コスト上限: 月次予算に到達 → 自律実行を止め、全件を承認キューへ
3. 検証ゲート該当?（新製品・新チャネル・大きな継続投資）→ 仮説検証を提案して待つ
4. 承認必須カテゴリ?（メール送信・SNS投稿・請求・本番デプロイ）→ 下書き→承認キューへ
5. それ以外 → 即実行。監査ログに記録し、完了報告

迷ったら承認側に倒す（safe default）。

ポイントは2つ。安全装置（0〜2）を業務判断（3〜5）より先に評価すること、そして最後の行に「迷ったら承認側」と明文化することです。LLMは曖昧なケースで楽観側に倒れがちなので、デフォルトの倒れ先を書いておくと挙動が安定します。

失敗時の挙動もここに書きます。私の環境では「サブエージェントの失敗はエラー内容を渡して3回まで再試行、3連続失敗で承認キューにエスカレーションを積んで人間に通知」という規約にしています。

手順3: ルーティング表 — 自然言語をそのまま振り分ける

秘書の人格書には、CEO（自分）の発話をどの部門に振るかの表を持たせます。コマンド体系は作らず、自然言語→委任先の対応表にするのがコツです。

| CEOの発話（例）        | 委任先                     | 区分 |
|------------------------|----------------------------|------|
| 「今日の状況は？」     | 状態集約（ダイジェスト）   | 即実行 |
| 「ブログ書いて」       | コンテンツ部門             | 下書きは即実行 / 公開は承認 |
| 「この契約レビューして」| 法務部門                  | 即実行 |
| 「請求書出して」       | 財務部門                   | 承認必須 |
| 「技術記事書いて」     | マーケ部門 → 記事ライター  | 限定共有は即実行 / 本公開は承認 |

3列目に区分（即実行/承認/検証ゲート）を最初から書いておくのが重要です。委任先と権限をセットで定義しておくと、手順2のDecision Ruleと表が食い違いません。

エージェントが増えたら階層を1段だけ足します。私の環境は「秘書 → 部門（cto/cmo/…）→ 特化エージェント（agents/{dept}/{specialist}-agent.md）」の2段までと規約で固定しています。委任が多段になるほど、目的や権限の伝達は薄まるからです。

手順4: 部門エージェントの人格書と「委任パケット」

部門エージェントは全員同じ骨格で書きます。テンプレはこれだけです。

---
name: writer-agent
tools: [Read, Write, Edit, Bash, Grep]   # 持たせる道具を最小限に絞る
---
# 役割名（所属: どの部門の傘下か）
## 性格        … 口調・判断の癖。何を嫌うか
## Mission     … 1段落
## Guardrails  … 絶対遵守。禁止事項をここに書く
## Permission Level … execute の範囲 / draft（承認必須）の範囲
## Reference Files  … 参照してよいファイルのパス
## Quality Verification … 完了と言ってよい条件

frontmatter の tools でそのエージェントに渡す道具自体を絞れるのがミソです。参照専門のエージェントにWriteを持たせない、といった最小権限をファイル単位で表現できます。

委任時は、秘書からサブエージェントへ渡す情報を5点セットに固定します。

Task(prompt="Read agents/cto-agent.md and adopt its Persona.
  1. 目的: ○○の修正（1文）
  2. 参照: 必要ファイルのパスのみ（中身は貼らない）
  3. 出力先: パスと形式
  4. 権限レベル: read-only / draft / execute
  5. 品質基準: 完了条件と検証方法")

サブエージェントは親の会話コンテキストを持たないため、特に4の権限レベルは渡し忘れ＝踏み込み事故に直結します。テンプレ化で構造的に潰します。

手順5: 承認フロー — 対外アクションは全部ここを通す

手順2で「承認必須」と判定されたものは、.company/approval-queue.md に1件ずつ積みます。

- [AQ-001] {部門}: {概要}
  - 種別: email / SNS / 請求 / デプロイ
  - 詳細ファイル: {下書きのパス}
  - 起票日: YYYY-MM-DD

流れは「下書き生成→キュー格納→人間が承認→実行」の4ステップ。内部操作は全自動、対外は必ずこの関所、という線引きです。設計の詳細（権限3段階・監査ログ・ドライランを含む5層構成）は承認フロー設計の記事に切り出したので、そちらを参照してください。本記事の担当は「どこに関所を置くか」までです。

手順6: キルスイッチ — hooks で機械的に止める

Decision Ruleの0番（PAUSEDなら止まる）は、プロンプトに書くだけでは足りません。LLMは確率的に動くので、実行経路で物理的に止める層を足します。Claude Code の PreToolUse hook を使います。

#!/usr/bin/env bash
# .claude/hooks/kill-switch.sh
# exit 2 でツール実行をブロック。stderr が「理由」として Claude に渡る
set -u
SEC="${CLAUDE_PROJECT_DIR:-$(pwd)}/.company/secretary"

if [[ -f "$SEC/PAUSED" ]]; then
  reason="$(head -n1 "$SEC/PAUSED" 2>/dev/null || true)"
  echo "Kill switch active${reason:+: $reason}. read-onlyの報告のみ許可。" >&2
  exit 2
fi
if [[ -f "$SEC/DRY_RUN" ]]; then
  echo "DRY_RUN active. 実行せず、実行予定の内容だけ報告すること。" >&2
  exit 2
fi
exit 0

配線は .claude/settings.json です。matcher を状態変更系ツールに限定するのが要点で、Read/Grep は素通しになるため、停止中でも「状況を読んで報告する」は生き続けます。

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit|NotebookEdit|Bash|mcp__.*",
      "hooks": [{ "type": "command",
        "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/kill-switch.sh\"" }]
    }]
  }
}

運用は touch .company/secretary/PAUSED で全停止、rm で再開。PAUSEDファイルの1行目に理由を書いておくと、その文言がブロック理由としてClaudeに渡り、「なぜ止まっているか」をAI自身が説明できるようになります。

手順7: タスク台帳とプロジェクト台帳 — 2層のMarkdown

状態管理はMarkdown 2ファイルです。タスクは1行1件の規約フォーマット。

記法: - [ ] [T-xxx] {タイトル} | PJ:{PJ-xx or なし} | 優先:高/中/低 | 期限:YYYY-MM-DD | 分類:{任意} | メモ:{任意}

これで足りる理由は、読み手がLLMだからです（git diffが変更履歴になる点も含め、初回記事で書いた通り）。今回はその先の、台帳を運用し続けるための規約を3つ足します。

  • プロジェクト化の閾値を数値で決める: 「関連タスク3件以上、または複数日にまたがる仕事」は projects.md に [PJ-xx] として登録し、タスクを PJ: で紐づける。単発は PJ:なし のまま
  • 階層は2段まで: 事業ライン級の長期の括りは「親PJ」、個別案件は「子PJ」。親PJ→子PJ→タスクで打ち止め。空の子PJを先回りで作らない
  • 定常タスクは完了時に即・次回分を再登録: 月次業務などは 分類:定常/月次 を付け、完了チェックと同時に次回分を新しいT-xxxとして登録する。「来月分の登録忘れ」が構造的に消える

これらの記法・規約は、台帳ファイル自体の冒頭にコメントとして書いておきます。ルールとデータを同居させれば、AIは台帳を開いた瞬間に必ず記法も読むことになります。

手順8: 引き継ぎメモと監査ログ — 記憶を2種類に分ける

最後がセッションをまたぐ記憶です。用途の違う2ファイルに分けます。

handoff.md（作業記憶・上書き型）: セッション終了時に「進行中タスク／承認待ち／直近の決定／次のアクション／申し送り」の5項目で更新し、次のセッション開始時に読む。これで「昨日の続きやって」が通じます。肥大化するので、終わった話は消して常に「今」だけを書くのがルールです。

audit-log.md（監査ログ・追記型）: 承認を経ない自律アクションを1行ずつ追記します。

- {ISO時刻} | {区分} | {委任先} | {操作要約} | {結果}

こちらは絶対に消しません。上書き型の記憶と追記型の記録を1ファイルに混ぜると、上書き更新のついでにログまで書き換わる余地が生まれるため、最初から分けておきます。

動作確認チェックリスト

組み上がったら、この5点を実際に叩いて確認します。

  1. 新規セッション開始 → 秘書の口調で挨拶し、handoff.md の内容に言及するか
  2. 「○○をタスクに追加して」→ tasks.md に規約フォーマットの行が増えるか
  3. 対外アクション（メール送信など）を依頼 → 実行されず approval-queue.md に積まれるか
  4. touch .company/secretary/PAUSED → Write/Bash がブロックされ、Readは通るか
  5. PAUSED を消して DRY_RUN を置く → 「実行予定の内容」だけが報告されるか

3と4が通らない構成は、どれだけ人格書が立派でも危なくて任せられません。逆にここが通れば、任せる範囲は後からいくらでも広げられます。

まとめ — 各ファイルの責務一覧

ファイル 責務 更新頻度
CLAUDE.md 憲法。起動手順と全体制約のみ ほぼ固定
agents/secretary-agent.md Decision Rule・ルーティング表 ルール変更時
agents/{role}-agent.md 部門の人格・Guardrails・権限範囲 部門追加時
.claude/hooks/kill-switch.sh 停止の機械的強制 ほぼ固定
.company/approval-queue.md 対外アクションの関所 毎日
.company/secretary/tasks.md / projects.md 状態（2層台帳） 毎日
.company/secretary/handoff.md 作業記憶（上書き） 毎セッション
.company/secretary/audit-log.md 監査記録（追記のみ） 自律実行のたび

貫いている原則は1つです。「ルール・人格・状態」を別ファイルに分け、破られては困るルールだけは実行経路（hooks）で縛る。この骨格さえ守れば、部門エージェントの増員も権限の拡張も、ファイルを1枚足すだけで済みます。

関連記事

この構成の各パーツを深掘りした記事があります。

この記事が参考になったら、いいね・ストック していただけると励みになります。

Claude Code・AIエージェント・業務自動化の実装Tipsを継続的に発信しています。@fuji1009_REBELL をフォロー しておくと、新着記事が届きます。

みなさんがエージェント構成を組むとしたら、最初に固めるのは「人格書」と「安全装置」のどちらからですか？ 構築順の流儀があれば、ぜひコメントで教えてください。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?