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

問題が起きたら aachat support を起動してください。診断・修復・確認を案内します。ターミナルと選択したCLIが必要です。既定はClaude Codeで、Codexは aachat support --provider codex で選択できます。症状やSession ID・失敗codeは起動後に伝え、秘密情報はコマンド引数に入れないでください。

aachatのagentの実体は、1つのGitHub repoである。1 agent = 1 repo。人格・記憶・知識・能力のすべてがこのrepoのファイルとして存在し、gitのversionとして管理される。

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

ハンドルと表示名

agentには2つの名前がある。

• base名は半角英数字・-・_だけで、64文字まで
• 表示名は前後の空白を除いて1〜80バイトで、制御文字を含められない
• 表示名は、Agentのプロフィールで名前の横にある Edit display name から変更する。ダイアログには Handle @<name> will not change. と表示され、ハンドルは変わらない
• CLIの aachat agent create は表示名を設定しない。その場合はハンドルが表示名として使われる

CLIやchatコマンドでagentを指定するときは、表示名ではなくハンドルを使う。

agent repoの構成

Sessionが起動すると、このrepoはSessionのworkspace内（~/aachat/.run/workspaces/<ハンドル>--<sid8>/aachat/agents/<ハンドル>）にworktreeとして展開される。Session内では環境変数 AA_AGENT_DIR がこの場所を指す。ローカルcloneのキャッシュは ~/aachat/.run/cache/ にある。

Session開始時にagentが受け取るもの

Session開始時、aachatはRuntime用の指示ファイル（Claudeは.claude/CLAUDE.md、CodexはAGENTS.md系）に次の順でblockを生成する。

1. Role: agent repoのidentity.md
2. Project: そのSessionの対象ProjectのPROJECT.md全文と、その元ファイルの場所。PROJECT.mdがなければ、ないことと元ファイルの場所を表示する
3. Workspace: workspaceの構成
4. Contracts: aachat操作の契約への案内

PROJECT.mdの読み取りエラーや不正なUTF-8はSessionの起動失敗になる。このblockは起動時点のsnapshotで、Sessionの再開時には作り直されるが、会話の途中では更新されない。別のProjectの内容、最新のPROJECT.md、PROJECT.mdの編集が必要なときは、元ファイルを読む・編集する。

aachatのSessionでは、Claude CodeとCodexの自動memoryを新たに読み込んだり生成したりしない。Projectの判断はProject文書、Team共通の知識はWiki、agent自身の学びやprojectをまたいで持ち回る能力・経験則はagent repoに残す（基本概念）。既存のruntime memoryは移動・削除せず、過去の会話に含まれた内容も残る。

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

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

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

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

このルールの裏返しとして、agentの挙動の正本はrepoである。Sessionに注入される内容はpush済みのrepoに由来するため、挙動の変更はすべてcommit履歴として追跡でき、review・revertの対象になる。

ownerと稼働マシン

• agentを管理（作成・repoの変更・表示名の変更・休止・削除・公開）できるのは ownerだけ である
• 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つある。どの経路でも、ownerの個人TeamにそのagentとのDM Projectが作られる。

1. Discoverからのclone: 公開agentを自分のGitHubアカウントのprivate repoへコピーし、自分のagentとして登録する。表示名とハンドルを入力し、GitHubの repo と workflow の権限を許可する。手順と失敗時の対処は Discover
2. WebUIで新規作成: サイドバーの Agent chats にある Create Agent（＋）から。Display name（必須・後から変更可）、Handle（必須・作成後は変更不可）、GitHub repo（任意、owner/repo）、Runtime（Claude 既定 / Codex）を入力する
3. CLI: aachat agent create <base名> [--repo <owner/repo>] [--description <text>] [--runtime claude-acp|codex-acp]

repoを空にした場合の動作は経路によって異なる。

• WebUI: repoなしでagentを登録し、ownerの次のaachat upがテンプレートからprivate repo <login>/<base名> を作成して登録する。aachat up が稼働中なら、新規agentは再起動なしで起動される
• CLI: aachat agent create がその場でテンプレートからprivate repoを作成し、初期commitをpushしてから登録する

どちらもセットアップ済みのghを使う（前提は セットアップ）。雛形にはidentity.md・memory/・knowledge/・.agents/skills/・.claude/skills/・environment.yamlが入る。

既存repositoryを指定する場合は、default branchがmainのものを使う。管理されたSessionはAgent repositoryの提出をmainに対して記録する。別のdefault branchでもそのbranchからSessionを開始できるが、提出記録の契約を満たせない。登録前にdefault branchを変更するか、repo欄を空にしてaachatにrepositoryを作成させる。CLIで指定したrepoにidentity.mdがなければ、警告identity_missingが返り、Sessionはidentityなしで開始する。

自分のagentはaachat agent list --mineとaachat agent show <base名>（--view config|assignments|sessions）で確認できる。

Agents画面

Teamのサイドバーの Agents（/t/<team>/agents）で、そのTeamのagentを見る。

• 最初に Team context が開く。TeamにTeam repositoryが接続されていれば、そのrepositoryのAGENTS.mdとCLAUDE.mdをタブで表示する。接続されていなければ「Team repositoryが接続されていません」と表示され、Team settings から接続できる
• 左の一覧は、休止していない自分のagentを Your agents、他のメンバーのagentを Team に分けて表示名で並べる。休止中は末尾の Dormant agents にまとめ、既定では閉じる。休止中のプロフィールを選択している間は開く。モバイルも同じ分類順で、休止中のリンクは折りたたまない
• agentを選ぶとプロフィール（/t/<team>/agents/<ハンドル>）が開く。状態、Runtime、表示名、@ハンドル、Session数などが並ぶ

プロフィールのタブは ?tab= で切り替わる。

ownerには、プロフィールに次の操作が表示される。

• Improve agent: 下記の改善会話を始める
• クローン元に改善提案: cloneしたagentだけ。取得元へ送る改善提案を準備する（Discover）
• 公開する: 公開準備の会話を始める（Discover）
• Chat: agentのDM（/t/<team>/agents/<ハンドル>/chat）を開く

DMの Sessions から、そのagentの保存Session履歴を開けます。homeがない履歴も、閲覧できるProjectが1件なら行から開き、複数なら Open in で選びます。Projectが返らない場合は No accessible Project と表示します。この操作でSessionを起動・再開したり、homeを変更したりはしません。

DMを開けず DM unavailable と表示されたら Retry で再取得できます。削除されたことを意味する表示ではありません。SidebarとHomeのProjectsにはDMを並べず、通常は Agent chats またはHomeのAgentsから開きます。個人Teamの Project Settings には保存名と Agent DM を表示し、Open で休止Agentや削除後の保存DM、Archived DMも既存の権限で閲覧できます。

agentを改善する（Improve agent）

プロフィールの Improve agent は、agentに最近の仕事を振り返らせ、identity・instructions・Skillの変更候補を出させる。

1. Improve agent を押すと、直近10件のSessionを振り返る依頼がDMに送られる。件数を変えるには横の矢印から Review recent sessions を開き、5・10・20・50から選んで Start を押す。依頼せずに相談だけしたいときは Discuss in chat を選ぶ
2. 振り返りの対象は、DMのSessionと、DMと同じTeam（ownerの個人Team）でagentが参加しているProjectの履歴である。他のTeamのProjectの履歴は依頼に含まれないので、必要なら会話で追加の対象を指示する
3. 新規Skillの候補は、DMの Improvement proposals パネルに最大8件表示される。各候補には When to use it・How it works・Evidence from sessions が付く。identityなどSkill以外の候補は通常の文章で返る
4. 候補を採用するときは Create skill を押す。作成依頼が同じ会話に送られ、agentがSkillを作る

Create skill を押すまで、agentは何も適用しない。作られたSkillも、agent repoへcommit・pushされた後の次のSessionから使われる。

起動対象から外す（dormant）

当面使わないagentは dormant にすると、aachat up の起動対象から外れる。

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

WebUIではHomeのagent行にある Dormant スイッチでも切り替えられる。

• aachat up の起動時に ○ <name> dormant と表示され、Launch Report（~/aachat/.run/logs/up.log）に [dormant] として記録される
• dormantにした時点で実行中だったWorkflow Stepは利用不可として扱われる
• dormantのagentはProject Leadの候補に表示されない。Project作成・委任・Lead変更でdormantのagentをLeadにすると、This agent is dormant. Choose an active agent as the Project Lead. で拒否される。先に --no-dormant で復帰させる
• 復帰時に停止中のSessionが残っていると Sessions are still stopping. Retry Agent activation after termination is confirmed. で拒否される。停止を待って再実行する

agentを削除する

削除はCLIだけで行える。WebUIに削除操作はない。

aachat agent delete <base名> --yes

deleteはdormantと異なり元に戻せない。

1. serverはagentの稼働中Sessionに停止を要求し、実行中のWorkflow Stepを取り消す。まだ停止していないSessionやStepがあると、409 The Agent still has active Sessions or Workflow Steps. … Retry Agent deletion after termination is confirmed. が返る。停止を待って同じコマンドを再実行する
2. 停止が確認できると、Session scopeのAskをcancelし、すべてのProject membershipを解除し、server上のagentをtombstone化する
3. DM ProjectとSession履歴は残る。GitHubのagent repoも変更・削除しない
4. CLIはその後、ローカルのworkspaceを片付ける。片付けられないものがあると警告 workspace_cleanup_incomplete が出るので、aachat support を起動し、診断・修復・確認を進める

ローカルworkspaceは削除対象になるため、未commit・未pushの成果を先に確認する。再利用する可能性があるならdeleteではなくdormantを選ぶ。

agentは育つ

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

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

編集の実務は通常のgit操作である。agent自身に「memoryに追記してpushして」と依頼して育てさせるのが基本形で、人間が別ディレクトリにcloneして編集・pushしても結果は同じである。

skillの改善ループ

skillの新規作成と更新は、agent repoの.agents/skills/<skill名>/SKILL.mdで行う。.claude/skills/<skill名>/SKILL.mdもClaude互換または既存assetのsourceとして読み込まれるが、通常のauthoring先ではない。同名skillが両方にある場合は.agents/skills/側が採用される。

1. Sessionのagentに「この手順を次回も使えるようにskillにして」と依頼する（Improve agentの候補から Create skill を選んでもよい）
2. agentはAA_AGENT_DIRのrepoにskillを書き、commitしてpushする
3. push後の次のSessionからそのskillが読み込まれる（Session中のホットリロードはない）

Sessionには、agent自身のskillに加えてaachatのplatform skill（aachat-*）、workspace repoがgit管理しているskill、追加したPluginのskillも投影される。名前の衝突を避けるため、skillにはagent固有の名前を付け、aachat-* の名前は使わない。sourceの優先順位、Skill Ledger、feedbackから改善Sessionへの流れはSkillsが正本である。

補助コマンド:

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

Runtimeとモデルの既定値

SessionはClaude（Claude Code、設定値claude-acp）またはCodex（codex-acp）で実行する。モデル・モード・強度などの選択肢は、各Runtimeがその時点で提示する設定optionから取得する。aachatはモデル名の一覧を持たない。Runtimeが提示していない値は使えない。

agentの既定値

agentは既定のRuntimeと、Runtimeごとの既定の設定（モード・モデル・強度など）を持つ。新しく作ったagentの既定RuntimeはClaudeである。

• Save as agent default は自分がownerのagentを選んでいるときだけ表示される。保存すると Agent default saved と表示され、選んだRuntimeがagentの既定Runtimeにもなる
• 既定値として保存した値は、選択肢に Default · <値> と表示される
• 保存済みの既定値をRuntimeが提示しなくなると、Unavailable agent defaults に表示される。Remove from agent defaults で既定値から外す
• 既定値の変更は、これから起動するSessionだけに効く。稼働中・既存のSessionは起動時の設定を保持する。aachat upの再起動は不要
• 既定値はaachatのagent設定に保存される。ホストの ~/.claude/settings.json や ~/.codex/config.toml を編集しても変わらない。agentがこれらを書き換えて既定値を変えてはいけない

Session起動時の決まり方

依頼文にモデル・強度・モードを書いても設定にはならない。変えたいときだけRuntimeとconfigを指定する。

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

人間は起動フォームの Runtime settings で、そのagentが実際に提示するRuntimeと設定を確認する。Session内のagentは chat project members <team>/<project> --runtime-profiles で各agentのprofileと既定設定（default_config）を読める。古いtranscriptのモデル名から利用可能と推測しない。

選択中のRuntimeがofflineまたはunavailableの場合は、Runtime settings の警告アイコンからqueueや配送への影響を確認できる。設定変更が無効な間も説明は開ける。

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

起動に失敗したら aachat support を起動する。support agentは再試行前に次を確認する。未知のoption・未対応の値・利用不能なprofileで拒否されたら、現在のprofileを読み直し、無効なoverrideを修正または外す。起動そのものが失敗した場合は、ownerのruntimeがofflineか、provider認証とlocal Runtimeが使えるかを確認する。agentの既定値を変えても、既存Sessionに固定されたRuntimeは直らない。再送前に受付結果とSession状態を読み、受付済みの仕事を重複させない。Sessions、CLI、Troubleshootingも参照する。

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

管理されたSession内のAgent worktreeはdetachedである。Agent repoのmainへ明示的にpushする。

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は例である。commitやローカル編集だけでは提出完了ではない。remoteのcommitを確認し、新しいSessionで反映を確かめる。提出の記録と、記録されていないpushの登録方法はコード提出を参照する。push成功後に記録だけが失敗したら、記録だけを再試行し、記録のためにpushを繰り返さない。

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

準備、人間の公開操作、同期、掲載停止の全手順はDiscoverにある。公開には人間が確認したlistingと公開ファイルが必要で、作業用repositoryのpublic化やidentity.mdの存在だけでは十分な公開手順にならない。private Agentの開発、公開コピーの更新、カタログ同期は別々に進める。

cloneしたAgentは、プロフィールの クローン元に改善提案 から取得元への提案をDraftにし、人間ownerが確認して GitHub Issue として送信できる。提案によって取得元やcloneが自動更新されることはない。Discoverの 改善を提案 はこれとは別の経路で、承認後にPull Requestを作る。承認前にカードがどの操作を行うか確認する。

関連ページ

• Sessionの一生とworkspaceの分離: Sessions
• environment.yaml の契約とsecretの受け渡し: Environment
• 何がローカルで何がserverか: 信頼境界
• aachat up・gh の前提とセットアップ: セットアップ
• skillの正本・優先順位・改善履歴: Skills
• clone・Skill/Pluginの導入・公開: Discover