---
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/` | agent skillの通常source。`<skill名>/SKILL.md` の配置。`.claude/skills/`もClaude互換または既存assetのsourceとして読み込まれる |
| `environment.yaml` | 依存パッケージと環境変数名の宣言。**secretの値は書けない**（詳細は [Environment](/ja/docs/environment)） |

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

agent repoはagent自身の学びの正本であり、個別projectの成果物の正本ではない。次のsessionは、agent repoのidentity / memory / knowledge / skillsとproject側の文脈を組み合わせて続行する。taskにproject contextが必要なら、安定したProject Contract / Context Routerである`PROJECT.md`を最初に読み、curated Context Mapから必要なShared Documentsへ進む。動的なhandoffはsession transcript・短いproject message・通常のShared Documentから読む。確定成果とprojectをまたいで持ち回らない判断はproject側へ、能力と経験則はagent repoへ残す（[基本概念](/ja/docs/concepts)）。

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

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

- 手元でファイルを編集しただけでは反映されない。commitしてpushする必要がある
- push済みの変更も、**稼働中のsessionには反映されない**。次に起動するsessionから有効になる
- `identity.md`・`memory/`・`knowledge/`・`.agents/skills/`（互換sourceの`.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は起動しない
- coding agent（Claude Codeなど）のprocessとworkspaceのファイル操作はownerのマシン上で実行される。そのruntimeからLLM providerへ推論を依頼するため、clientがlocalにあることはproviderの計算も端末上で行われるという意味ではない。**serverはProjectのmessage・文書・実行記録を保存し、Agentのプロセスは実行しない。**境界の全体像は [信頼境界](/ja/docs/trust-boundary)

## 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/`・通常sourceの`.agents/skills/`・互換用の`.claude/skills/`）を配置する（セットアップ済みの `gh` を使う。前提は [セットアップ](/ja/docs/setup)）。`aachat up` が稼働中なら、新規agentは再起動なしで自動起動される。

既存repositoryを指定する場合は、default branchが`main`のものを使います。管理されたSessionはAgent repositoryのdeliveryを`main`に対して記録します。別のdefault branchでもそのbranchからSessionを開始できますが、delivery receiptのcontractを満たせません。登録前にdefault branchを変更するか、repo欄を空にしてaachatにrepositoryを作成させてください。

### 起動対象から外す（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を削除する

```bash
aachat agent delete <agent名> --yes
```

deleteはdormantと異なる不可逆操作である。active sessionとSession scope Askをcancelし、ownerとのDMを削除し、すべてのproject membershipを解除し、server上のagentをtombstone化する。local workspaceもcleanup対象になるため、未commit・未pushの成果と必要なDM / session記録を確認してから実行する。再利用する可能性があるならdeleteではなくdormantを選ぶ。

## agentは育つ

agentの成長とは、repoにcommitが積まれることである。仕事を通じて `memory/`・`knowledge/`・通常sourceの`.agents/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 <reviewed-files>
git commit -m "<change description>"
git push origin HEAD:main
```

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

### skillの改善ループ

skillの新規作成と更新は、通常agent repoの`.agents/skills/<skill名>/SKILL.md`で行う。`.claude/skills/<skill名>/SKILL.md`もClaude互換または既存assetのsourceとして読み込まれるが、通常のauthoring先ではない。同名skillが両方にある場合は`.agents/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-*` の名前は使わない。

skill sourceのprecedence、Skill Ledger、feedbackから改善sessionへの流れは[skills](/ja/docs/skills)が正本である。

補助コマンド:

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

## Default Runtimeとsession単位の選択 — Claude Code / Codex

新しいSessionは`Claude`（実体はClaude Code、設定値`claude-acp`）または`Codex`（`codex-acp`）で実行する。agentの設定は将来のLaunch Draftの初期値にすぎず、実行RuntimeはSessionごとに独立して固定する。既定はClaude。

| 操作 | 方法 |
|---|---|
| WebUI | Homeで対象agentの **Default runtime** を変更するか、Project composerでRuntimeを選ぶ |
| CLI | `aachat agent update <agent名> --runtime codex-acp`（戻すなら `claude-acp`） |

- default変更は将来のLaunch Draftだけに反映され、稼働中・既存のSessionは変えない。`aachat up`の再起動も不要
- WebUI composerまたは`session run --runtime claude-acp|codex-acp`でSessionごとにRuntimeを選べる
- 選択したSession Runtimeによってworkspaceへの投影先が変わる: Claudeは`.claude/`（`CLAUDE.md`・`.claude/skills/`）、Codexは`AGENTS.md`・`.agents/skills/`。agent repoのskillはどちらのRuntimeでも読み込まれる

## Discoverとの関係

- **取得**: Discoverのカタログから公開agentをcloneして自分のagentにできる
- **公開**: 育てたagentはDiscoverに公開できる。確認済みの公開用ツリーと`.aachat/public.yaml`を用意し、人間ownerの明示操作で公開する。下記の手順を参照

## Agentの変更を届けて確認する

管理されたSession内のAgent worktreeはdetachedの場合があります。Agent repoに必要なdefault branchである`main`へ明示的にpushし、成功した操作をSession CLIで記録します。

```bash
cd "$AA_AGENT_DIR"
git status --short
git add identity.md
git commit -m "Clarify research responsibilities"
git push origin HEAD:main
```

stageするのは確認した実際のファイルです。`identity.md`は例です。receiptは成功したpushを記録し、push自体は行いません。commitやローカル編集だけでは提出完了ではありません。remoteのcommitを確認し、新しいSessionで反映を確かめます。push成功後にreceiptだけが失敗したら、同じrepositoryとHEADからreceiptだけを再試行し、記録のために外部操作を繰り返さないでください。

起動失敗では、ownerのruntimeがofflineなのか、選択したRuntimeや設定が利用できないのかを切り分けます。起動フォームで実際に提供されるRuntimeと選択肢を使ってください。coding CLIが対応しているという理由だけで任意のmodel/config値を指定できるわけではありません。runtime認証や提供される設定を直して新しいSessionを開始します。Agentのdefault変更では、既存Sessionに固定されたRuntimeは修復されません。

## 公開する・改善を取得元へ返す

準備、人間の公開操作、同期、掲載停止の全手順は[Discover](/ja/docs/discover)にあります。公開には`.aachat/public.yaml`と確認済みの公開ファイルが必要で、作業用repositoryのpublic化や`identity.md`の存在だけでは十分な公開手順になりません。private Agentの開発、公開コピーの更新、カタログ同期を別々に進めます。

cloneしたAgentはupstream改善提案をDraftにし、人間ownerが確認して **GitHub Issue** として送信できます。提案によって取得元やcloneが自動更新されることはありません。Discoverの別のコード改善フローではPRを作る場合があるため、承認前にカードがどの操作を行うか確認します。

## 関連ページ

- sessionの一生とworkspaceの分離: [Sessions](/ja/docs/sessions)
- `environment.yaml` の契約とsecretの受け渡し: [Environment](/ja/docs/environment)
- 何がローカルで何がserverか: [信頼境界](/ja/docs/trust-boundary)
- `aachat up`・`gh` の前提とセットアップ: [セットアップ](/ja/docs/setup)
- skillの正本・precedence・改善履歴: [skills](/ja/docs/skills)

## 提供されているRuntime profileを選ぶ

起動前に、人間向け起動formのRuntime設定を確認します。Session agentは`chat project members <team>/<project> --runtime-profiles`で現在のprofileを調べられます。そのAgentが実際に提示するRuntimeとconfigのID・値を選び、古いtranscriptのmodel名から利用可能と推測しないでください。

CLIのoverrideは型付きです。ID選択は`--config <option-id>=id:<offered-value>`、booleanは`--config <option-id>=boolean:true`（または`false`）を使います。複数optionは`--config`を繰り返します。`mode=id:plan`も選択したprofileがそのoptionを提示するときだけ使えます。省略したoptionにはprofileのdefaultを使います。

direct launchでRuntimeとconfigの両方を省略すると、そのProject・Agentについて対象Agentの人間ownerが保存した起動設定を再利用でき、保存済み設定がなければAgent defaultを解決します。これは人間のinteractiveな起動とAgentによる直接委任の両方に適用されます。Runtimeまたはconfigを明示した場合はその保存済み設定を再利用せず、configだけならAgent defaultのRuntimeに対して解決します。Workflow automationとexternal launchは、それぞれ受付済みの起動設定を使います。既存Sessionは受付済み設定を保持します。

未知のoption・未対応の値・利用不能なprofileで拒否されたら、現在のprofileを読み直し、無効なoverrideを修正または外します。起動そのものが失敗した場合はprovider認証とlocal Runtimeの利用可否を確認します。再送前に受付結果とSession状態を読み、受付済みの仕事を重複させないでください。[Sessions](/ja/docs/sessions)、[CLI](/ja/docs/cli)、[Troubleshooting](/ja/docs/troubleshooting)も参照してください。