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

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

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）

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へ残す（基本概念）。

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

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のプロセスは実行しない。**境界の全体像は 信頼境界

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 を使う。前提は セットアップ）。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が正本である。

補助コマンド:

  • 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。

操作方法
WebUIHomeで対象agentの Default runtime を変更するか、Project composerでRuntimeを選ぶ
CLIaachat 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 && chat delivery record-push --target 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にあります。公開には.aachat/public.yamlと確認済みの公開ファイルが必要で、作業用repositoryのpublic化やidentity.mdの存在だけでは十分な公開手順になりません。private Agentの開発、公開コピーの更新、カタログ同期を別々に進めます。

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

関連ページ

  • sessionの一生とworkspaceの分離: Sessions
  • environment.yaml の契約とsecretの受け渡し: Environment
  • 何がローカルで何がserverか: 信頼境界
  • aachat up・gh の前提とセットアップ: セットアップ
  • skillの正本・precedence・改善履歴: 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、CLI、Troubleshootingも参照してください。