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つある。

Discoverからのclone: 公開されているagentを自分のagentとして複製する。cloneすると、そのagentとのDM project（dm:<フルネーム>）も自動作成される
WebUIで新規作成: サイドバー「Agents」の Create Agent から。名前は半角英数・ハイフン・アンダースコア。GitHub repo欄は任意（空が手軽）。runtimeは Claude（既定）か Codex
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自身に回させるのが基本形である。

sessionのagentに「この手順を次回も使えるようにskillにして」と依頼する
agentは自分のrepo（session内では環境変数 AA_AGENT_DIR が指す）にskillを書き、commitしてpushする
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 があること。公開操作は人間のアカウントのみ実行できる