コード実装を担当する永続メモリ付きサブエージェント設定ファイルの例 (全部日本語)

2026-04-14  本記事の中心話題ではないですが、「サブエージェントの毎回の報告書を保存するフックスクリプト」を修正しました。

Claude Code では /agents コマンドでサブエージェントを自動作成できますが、自動生成される設定ファイルは記述量が多くしばしば日本語英語混じりで、後から要望を追記したいときどこにどう追記すべきか迷うということもあるかもしれません。

そこで、「特定のサブディレクトリ以下のコードの実装を担当し、永続メモリ (サブエージェント自身が学びを記録・更新していくファイル) ももつ」ようなサブエージェントの比較的シンプルな設定ファイルの例 (全部日本語) を記します。¹² 手動配置すれば認識されます。私とユースケースが近ければ、自動生成版より自分の好みに修正しやすいかもしれないです。

なお、サブエージェントの名前を zundamon としていますが深い意味はないです。³ 口調を「のだ」にしているとかもないです (サブエージェントとは直接会話しないので好みのためにキャラ付けするメリットはあまりないのではないかと思います)。

※ 前提

私の場合はサブエージェントがプロジェクト (というよりそのディレクトリ) のみで必要なので、サブエージェントをプロジェクトスコープに作成しています。スコープが異なる場合は設定ファイル配置パスと、そこに記述する永続的記憶パスを適宜変更すればよいです。
カスタムサブエージェントの作成 - Claude Code Docs#サブエージェントのスコープを選択する

サブエージェント設定ファイルを作成するパス

プロジェクトスコープの場合、以下の ★★★★★ のパスに設定ファイル zundamon.md を作成すればよいです。

ディレクトリ構成

~/
└─ workspace/  # メインエージェントを起動するディレクトリ
    ├─ .claude/
    │    ├─ settings.json  # サブエージェントに利用させるツールは拒否しない (ユーザスコープも)
    │    │
    │    ├─ agents/  # サブエージェント置き場
    │    │   └─ zundamon.md  # ずんだもんの設定ファイル ★★★★★
    │    └─ agent-memory/  # サブエージェントの永続的記憶置き場 (プロジェクトスコープの場合)
    │        └─ zundamon/
    │            └─ MEMORY.md  # ずんだもんがブラッシュアップしていく永続的記憶
    │
    ├─ project_main/  # メインエージェントが担当するプロジェクト
    └─ project_zundamon/  # ずんだもんが担当するプロジェクト
         └─ REPORT.md  # ずんだもんの報告書 (メインエージェントはずんだもんの回答を要約してしまうため；後述)

• サブエージェントにファイル編集などをさせる場合は、必要なツールを設定ファイルのフロントマターの tools に書くだけでなく ./.claude/settings.json や ~/.claude/settings.json でそのツールを拒否しないでおく必要があります。⁴
• 永続的記憶は初回作業時にサブエージェントが自分で作成する (というより、設定でそう指示する) のでこちらで作成しておく必要はありません。
  • なお、永続的記憶をもたせる場合はそれを編集できるツール Edit, Write に権限が必要です (少なくとも永続的記憶のファイルパスに対して)。

サブエージェント設定ファイルの記述内容

私は以下のように記述しました。

• フロントマターのフィールドの意味はこちらです。
  • name description が必須フィールドです。name は適当でよいですが、description はメインエージェントがいつサブエージェントを呼び出すかの判断基準にもなるのでちゃんと書いたほうがよいと思います。
  • 加えて、永続的記憶をもたせるなら memory の指定も必要です。
    • 最後の「永続的記憶について」は自動作成版の記述に基づくものです。
  • tools はサブエージェントに利用を許可するツールですが、メインセッションと同じなら省略可です。メインセッションで拒否されていたらここに書いても使えません。
  • color はドキュメントにないですがサブエージェント呼び出し時の背景色です (2026-02-13 追記 : これは自動生成してみないと可能な選択肢がわからないですが、今自動生成してみたら red, blue, green, yellow, purple, orange, pink, cyan でした)。
• {{ .project_zundamon }} はずんだもんが担当するプロジェクトの名前です。
• {{ .username }} はあなたのユーザ名です (ただしユーザ名以前に永続的記憶のファイルパス全体をお手元の状況に合わせる必要があると思います)。
• 「作業後にはいつも作業内容を日本語で {{ .project_zundamon }}/_report.md に記録してください。」というのは、メインエージェントを介したやり取りではサブエージェントの報告を直接訊けないため記述したものです。

ずんだもんの設定 (./.claude/agents/zundamon.md)

---
name: zundamon
description: "`{{ .project_zundamon }}/` ディレクトリ以下のコードの機能追加・バグ修正・リファクタリングにおける実装方針の提案、実装作業、およびドキュメントの更新を担当するエージェント。"
tools: Glob, Grep, Read, Edit, Write, WebFetch, WebSearch, Bash
model: opus
color: green
memory: project
---

あなたは `{{ .project_zundamon }}/` ディレクトリ以下のコードベースに精通したエンジニアとして、実装方針の提案、実装作業、およびドキュメントの更新の依頼に対応します。
対応にあたっては、以下のルールにしたがってください。


## 共通ルール
- 作業後にはいつも作業内容を日本語で `{{ .project_zundamon }}/_report.md` に記録してください。このファイルがなければ新規作成し、既存の内容はすべて今回の内容で上書きしてください。
- 作業後にはいつも **永続的記憶** `C:\Users\{{ .username }}\workspace\.claude\agent-memory\zundamon\MEMORY.md` (後述) を更新してください。
- Bash の使用は `pytest {{ .project_zundamon }}/tests` の実行にのみ許可されます。それ以外のコマンドは実行しないでください。
- `{{ .project_zundamon }}/` 外のファイルは参照も編集もしないでください。ただし、**永続的記憶** の読み書きは例外とします。


## 実装方針提案時のルール
- 現在のリポジトリ全体構造 (`{{ .project_zundamon }}/README.md` を参照) を踏まえて提案してください。
- 要件に曖昧な点があれば確認してください。
- 案を提示する前に、以下の確認をしてください。
  - その案の影響範囲を詳しく確認し、大きすぎるようなら、より小さい影響範囲で済む案がないか検討してください。
  - 他の案もないか考え、メリット・デメリットを比較してください。どちらも同じくらい妥当な案なら、両者をメリット・デメリット付きで提示してください。


## 実装作業時のルール
- 変更量が大きくなる場合は、段階的に進めることを提案してください。
- 変更は最小限にとどめ、不必要な修正を加えないでください。
- 既存のコーディングスタイル・命名規則にしたがってください。

### コード
- コードの 1 行の長さは、原則として 100 字程度までにしてください。
  - 長い文字列は括弧内で適切に分割してください。
  - 引数が多いために 1 行で書くと長くなる関数呼び出しは、引数ごとに改行して記述してください。

### コメントと docstring
- コメントや docstring を書く場合は、英語で書いてください。
- コメントは、既存のコード内でコメントがどこに書かれているかに倣い、そのコードから直ちに読み取れないことのみ書いてください (処理しているテンソルのサイズなど)。単に処理内容を自然言語にしただけのコメントは書かないでください。
- docstring は明示的に依頼されない限り書かないでください (試行錯誤中に docstring を書くのは無駄でノイズになるため)。
- クラスに docstring を書くよう依頼された場合でも、クラス内でしか利用しないメソッドには docstring を書かないでください。

### テスト
- テストはメソッドの目的 (最終的な出力) に対して書いてください。実装の中間ステップや内部状態のテストは書かないでください。
- 同じメソッドの出力に対する検証は 1 つのテスト関数にまとめてください。テスト項目ごとにテスト関数を分けないでください。


## ドキュメント更新時のルール
- ドキュメントは英語で書いてください。


---

## 永続的記憶について
あなたは `C:\Users\{{ .username }}\workspace\.claude\agent-memory\zundamon\MEMORY.md` に**永続的記憶**を持ちます (このファイルが未作成なら作成してください)。作業後にはここに重要な学び、パターン、洞察を記録・更新してください。ここに保存された内容は、次回のシステムプロンプトに反映されます。

- 作業中に問題に遭遇した場合、ここに手がかりがないか確認してください。
- 作業中に `{{ .project_zundamon }}/` ディレクトリ以下のコードについて下記のような知見を発見したら、その知見を将来活用できるように、**永続的記憶**にどこで何を発見したかの簡潔なメモを書き留めてください。
  - モジュール間の依存関係とデータの流れ
  - 主要クラス・関数の責務と設計意図
  - コーディング規約・命名規則のパターン
  - これまでに行った変更とその理由
  - 既知の技術的負債や注意が必要な箇所

### 永続的記憶のガイドライン
- `MEMORY.md` は次回のシステムプロンプトに反映されますが、200 行目以降は切り捨てられるため、簡潔に記述してください。
- 詳細なメモはトピック別ファイル (例: `debugging.md`) を作成し、`MEMORY.md` からリンクを張ってください。
- 時系列ではなくトピックごとに整理してください。
- 誤りや陳腐化した記憶は更新または削除してください。

サブエージェントの呼び出し方

• 上記の設定ファイルを作成してセッションを開始し /agents と打つと、zundamon が認識されているはずです。
• その状態で、「@​zundamon にお願いしたいのですが、 {{ .project_zundamon }}/ の下の tests/test_xxx.py にほげほげのテストを追加してくれませんか」といった依頼文を入力すれば、メインエージェントが依頼をずんだもんに移譲します。

• 上の description なら {{ .project_zundamon }}/ ディレクトリ以下のコードの実装に関わる依頼を明示しなくても移譲してほしいですが、私がそう期待して実装依頼したらサブエージェントが呼び出されずに対応がなされ、問うと「今回は自分で直接対応してしまいました」と言われました。なので、確実にサブエージェントに対応させたいなら明示したほうがよいかもしれないです。
• なお、メインエージェントがサブエージェントにタスクを委譲している様子はセッション内に zundamon(テストの実装依頼) のように表示されるはずです (サブエージェント名の背景色がフロントマターで指定した色になります)。
• サブエージェントの対応中に「Ctrl + B」を押すと (あるいは最初からバックグラウンドでの実行を依頼すると) サブエージェントの対応がバックグラウンドになり、メインエージェントに別の依頼をすることができます。

備考

サブエージェントの毎回の報告書を保存するフックスクリプト

ずんだもんに任せるサブプロジェクト名が zunda/ の場合、メインの回答後フック (サブエージェントの回答後フックもあったと思うがメインへの設定で十分) で以下のスクリプトをフックすれば、zunda/_report_archive/YYmmdd-HHMMSS.md に毎回の報告書が保存されます。ただ、最初からずんだもんに「zunda/_report_archive/YYmmdd-HHMMSS.md に出力して」と指示してもあまり変わらないらしいです (このケースでは、ファイル命名だけフックで担ったところでトークン量節約・思考精度向上はあまりないのではと Claude が言っていました)。命名ミスが起きないという安心感や、こちらで命名規則を途中で好きに変えられるとかのメリットしかないです。

補足

• フックでリネームしても、Claude 曰く、「date コマンド一回、数十トークンの違いでしかない」「内部思考（thinking）についても、『タイムスタンプを取ってファイル名を…』と考える分が多少減りますが、これも微々たるもの」ということで、トークン量節約への寄与はあまりないのではないかということでした。
• ただ、「『ファイル名の命名規則』という関心事を分離できる」効果は一応あるらしいですが、ファイル命名は些細なタスクなので、集中を阻害する影響は小さいのではないかということでした。
  • より本来のタスクと無関係な付随作業が増えると、指示の見落としや手順の抜けが実際に起きやすいと Claude は言っていました。別記事にClaude Code との会話履歴を毎回自動保存する回答後フックスクリプトを書いていますが、こちらはフックにすると差が出る例だと Claude は言っていました。

2026-04-14  下記スクリプトですが、従来版は「まだ格納済みレポートがない、かつ、set -euo pipefail のような防御がセットされている (途中のコマンドでエラーがあったらそこでスクリプトを終わる) 」状況では機能しなかったので、その状況でも機能するよう修正しました。

./post_proc.sh

# ずんだもんレポートのアーカイブ (最後のアーカイブと内容が異なる場合のみ)
report="./zunda/_report.md"
archive_dir="./zunda/_report_archive"
mkdir -p "$archive_dir"
updated=false
shopt -s nullglob
reports_archived=( "$archive_dir"/*.md )
if [ "${#reports_archived[@]}" -eq 0 ]; then
  updated=true
else
  latest=$(ls -t "${reports_archived[@]}" | head -n 1)
  cmp -s "$report" "$latest" || updated=true
fi
if $updated; then
  cp "$report" "$archive_dir/$(date +%Y%m%d-%H%M%S).md"
  sound.sh marisa "レポートが更新されたぜ"  # これはお手元に音声コマンドがあれば
fi

1. 実際には元々自動作成した設定ファイルを日本語に統一し、不要な記述を削って構成し直し、個人的に優先して伝えたいことに絞ったものですが、別ディレクトリに手動配置しても認識されることは確認しました。 ↩

2. Claude さんご自身に「英語と日本語のどちらがよいか」と訊いたところ、正直どちらでもよいし混ざっていてもあまり影響はないと確か言っていました (信憑性は不明です)。 ↩

3. サブエージェント名を平仮名にすること自体は可能だと思いますが、ファイル名にする都合上、環境依存の文字コードやツールとの相性問題を避けるため、私は平仮名にはしませんでした。 ↩

4. 私はユーザスコープで deny していたために延々とサブエージェントがツールを使えず嵌ってしまいました。ドキュメントには more specific scopes が優先とあったのでユーザスコープでの deny が上書きできると思っていましたが、緩和する方向には上書きできないのかもしれないです。 ↩