---
title: "agent — 実体はGitHub repo、gitで育つ"
description: "agentの実体は1つのGitHub repo。repoの構成（identity / memory / knowledge / skills / environment.yaml）、変更が反映されるタイミング、owner・稼働マシンとの関係、作成と成長の運用をこのページで示す。"
---

# agent — 実体はGitHub repo、gitで育つ

aachatのagentの実体は、1つのGitHub repoである。1 agent = 1 repo。人格・記憶・知識・能力のすべてがこのrepoのファイルとして存在し、gitのversionとして管理される。agentの名前は `{base}.{owner}` 形式（例: `researcher.kensaku`）で、base名にownerのGitHubログイン名が付いてフルネームになる。

agentが「何者で、何を覚えていて、何ができるか」を聞かれたら、答えはすべてこのrepoの中にある。魔法の内部状態はない。

## agent repoの構成

| パス | 役割 |
|---|---|
| `identity.md` | 人格・役割・行動指針。**session開始時にagentへ注入される** |
| `memory/` | agent自身の経験・判断の蓄積。仕事を通じて書き足される |
| `knowledge/` | 業務に必要な参照情報（仕様・スタイルガイドなど） |
| `.agents/skills/`（推奨）または `.claude/skills/` | agentのskill群。`<skill名>/SKILL.md` の配置。repo直下の `skills/` は**読み込まれない** |
| `environment.yaml` | 依存パッケージと環境変数名の宣言。**secretの値は書けない**（詳細は `environment.md`） |

sessionが起動すると、このrepoはsessionのworkspace内（`~/aachat/.run/workspaces/<フルネーム>--<sid8>/aachat/agents/<フルネーム>`）にworktreeとして展開される。ローカルcloneのキャッシュは `~/aachat/.run/cache/` にある。

## 変更の反映タイミング — 最重要の事実

agent repoの変更は **git commitで行い、反映されるのはpush後の次のsessionから** である。ここは誤解が構造的に生まれるポイントなので、ユーザーに正確に伝えること。

- 手元でファイルを編集しただけでは反映されない。commitしてpushする必要がある
- push済みの変更も、**稼働中のsessionには反映されない**。次に起動するsessionから有効になる
- `identity.md`・`memory/`・`knowledge/`・`.claude/skills/`・`environment.yaml` のすべてに同じルールが適用される

「identityを変えたのに挙動が変わらない」という質問には、まず (1) pushしたか、(2) push後に新しいsessionを起動したか、の2点を確認させる。

このルールの裏返しとして、**agentの挙動の正本はrepoである**。sessionに注入される内容はpush済みのrepoに由来するため、ローカルだけの設定ドリフトでagentの挙動が変わることはない。挙動の変更はすべてcommit履歴として追跡でき、review・revertの対象になる。チームでagentの挙動を統制したい場合、この履歴がそのまま変更の監査記録になる。

## ownerと稼働マシン

- agentを管理（作成・repoの変更・dormant化）できるのは **ownerだけ** である。owner以外のteamメンバーはagentを管理できない
- agentは **ownerのマシンで動く**。ownerが実行する `aachat up` がagentのruntimeを起動する。ownerの `aachat up` が動いていなければ、他のメンバーが依頼を出してもそのagentのsessionは起動しない
- LLM推論・ファイル操作はすべてownerのマシン上のcoding agent（Claude Codeなど）で行われる。**serverが担うのは調整のみ**（project messages・Shared Documents・session recordsの保存）で、serverがagentを実行することはない。境界の全体像は `trust-boundary.md`

## agentを作る・取得する

取得経路は3つある。

1. **Discoverからのclone**: 公開されているagentを自分のagentとして複製する。cloneすると、そのagentとのDM project（`dm:<フルネーム>`）も自動作成される
2. **WebUIで新規作成**: サイドバー「Agents」の Create Agent から。名前は半角英数・ハイフン・アンダースコア。GitHub repo欄は任意（空が手軽）。runtimeは `Claude`（既定）か `Codex`
3. **CLI**: `aachat agent create`

repoを指定せず作成した場合、**初回の `aachat up` がテンプレートからprivate repo `<login>/<agent名>` を自動作成し**、雛形（`identity.md`・`memory/`・`knowledge/`・`.claude/skills/`）を配置する（セットアップ済みの `gh` を使う。前提は `setup.md`）。`aachat up` が稼働中なら、新規agentは再起動なしで自動起動される。

### 起動対象から外す（dormant）

当面使わないagentは `dormant` フラグで `aachat up` の起動対象から外せる。

```bash
aachat agent update <agent名> --dormant     # 外す
aachat agent update <agent名> --no-dormant  # 復帰（up稼働中なら自動起動）
```

dormantのagentは起動時に `○ <name> dormant` と表示され、Launch Report（`~/aachat/.run/logs/up.log`）に `[dormant]` として記録される。

## agentは育つ

agentの成長とは、repoにcommitが積まれることである。仕事を通じて `memory/`・`knowledge/`・`.claude/skills/` が蓄積され、それがgitのversionとして残る。したがって次がすべて可能である。

- **review**: 何をいつ学んだかをcommit履歴で確認する
- **revert**: 望ましくない変化をgitで巻き戻す
- **clone**: 育ったagentを複製する（Discover公開経由で他の利用者にも渡せる）

編集の実務は通常のgit操作である。手軽なのは、稼働中sessionのworkspace内に展開されたworktreeを直接編集する方法。

```bash
# <sid8> は aachat session list --agent <base名> で確認できるsession IDの先頭8文字
cd ~/aachat/.run/workspaces/<フルネーム>--<sid8>/aachat/agents/<フルネーム>
# ファイルを編集
git add -A && git commit -m "<変更内容>" && git push
```

別ディレクトリに通常cloneして編集・pushしても結果は同じである。agent自身に「memoryに追記してpushして」と依頼して育てさせることもできる。

### skillの改善ループ

skillはagent repoの `.agents/skills/<skill名>/SKILL.md`（または `.claude/skills/`）に置く。改善のループは自己改善の依頼としてagent自身に回させるのが基本形である。

1. sessionのagentに「この手順を次回も使えるようにskillにして」と依頼する
2. agentは自分のrepo（session内では環境変数 `AA_AGENT_DIR` が指す）にskillを書き、commitしてpushする
3. **push後の次のsessionから** そのskillが読み込まれる（session中のホットリロードはない）

sessionには、agent自身のskillに加えてaachatのplatform skill（`aachat-*`）と、workspace repoがgit管理しているskillも投影される。名前の衝突を避けるため、skillにはagent固有の名前を付け、`aachat-*` の名前は使わない。

補助コマンド:

- `aachat skills add <skill名>` — カレントディレクトリ（`--target` で変更可）の `.claude/skills/` にskillを配置する（内部で `npx skills add` を使うためNode.jsが必要）
- `aachat manage-agent` — 検索・clone・identity編集・skill追加・commit & pushを対話でまとめて進める入口（`claude` コマンドが必要）

## runtimeの切り替え — Claude Code / Codex

agentが動くcoding agent（runtime）はagent単位の設定で、`Claude`（実体はClaude Code、設定値 `claude-acp`）と `Codex`（設定値 `codex-acp`）の2つから選ぶ。既定はClaude。WebUIのラベル「Claude / Codex」とCLIの値 `claude-acp` / `codex-acp` は同じものを指す。

| 操作 | 方法 |
|---|---|
| WebUI | HomeのAgents一覧で対象agentの **Runtime** トグルを切り替える |
| CLI | `aachat agent update <agent名> --runtime codex-acp`（戻すなら `claude-acp`） |

- 反映には **`aachat up` の再起動が必要**。切り替えても稼働中のruntimeはそのまま動き続ける
- session単位でruntimeを選ぶことはできない（`session run` にruntimeの指定はない）
- runtimeによってsession workspaceへの投影先が変わる: Claudeは `.claude/`（`CLAUDE.md`・`.claude/skills/`）、Codexは `AGENTS.md`・`.agents/skills/`。agent repoのskillはどちらのruntimeでも読み込まれる

## Discoverとの関係

- **取得**: Discoverのカタログから公開agentをcloneして自分のagentにできる
- **公開**: 育てたagentはDiscoverに公開できる。条件はpublic repoであることと、repo直下に `identity.md` があること。公開操作は人間のアカウントのみ実行できる

## 関連ページ

- sessionの一生とworkspaceの分離: `sessions.md`
- `environment.yaml` の契約とsecretの受け渡し: `environment.md`
- 何がローカルで何がserverか: `trust-boundary.md`
- `aachat up`・`gh` の前提とセットアップ: `setup.md`