gjalla-onboard

gjalla をオンボーディングする

完了時には、次の3つが満たされています。

1. このユーザーが実際に使っているコーディングエージェント向けに gjalla が設定され、意識する必要なく、今後のセッションがすべて記録されます。MCP やフックを設定してエージェントの設定にコミットするなど、このユーザーにとって適切な方法を選んでください。
2. このユーザーが使っているすべてのエージェントを対象に、直近1週間の作業が遡って取り込まれ、分類されています。これにより、ユーザーはすぐに gjalla で内容を確認できます。
3. チームのほかのエージェントにも役立つローカルのエージェントメモリーが、gjalla のメモリーに保存されています。個人的なメモリーや機密性の高いメモリーは含めず、チームやプロジェクトに関連し、チームのメンバー全員に役立つメモリーだけを保存してください。

以下は、この状態を実現するためのガイドです。効率よく作業できるよう、参考としてシェルのスニペットを掲載していますが、実行環境によって調整が必要な場合があります。

完了すると、チームのコーディングエージェントのワークフローのアクティビティやコストを把握し、成果を最適化するためのプラットフォームである gjalla を使えるようになります。その後は、gjalla を常に活用できる永続的なメモリーシステムとして利用できます。gjalla の具体的な機能については、サイト https://gjalla.io をご覧ください。

0. gjalla の対象範囲と現在の作業場所の確認

gjalla の一部の機能は複数のリポジトリを横断してチーム全体に適用できますが、コーディングエージェントのアクティビティを把握し、適切に帰属させるには、git のコミットと併せて確認するのが最適です。そのため、現在の場所を確認し、git リポジトリ内にいるかどうかを調べてください。リポジトリ内にいない場合は、実際にどこにいるのか、また、ユーザーが gjalla を設定したいと考えている git リポジトリがどこにあるのかを確認してください。たとえば、複数の関連する可能性があるリポジトリを含む親ディレクトリを、既定の作業場所にしているユーザーもいます。担当範囲にあるプロジェクトのうち、gjalla にオンボーディングすることが重要、またはユーザーが希望しているものを特定し、それらを対象にしてください。

1. CLI

次に、CLI がインストールされているか確認します。

command -v gjalla || pipx install gjalla || uv tool install gjalla

どれも使えない場合は、以降の gjalla ... コマンドをすべて uvx gjalla ... に置き換えてください。uvx もない場合は、不足しているツールをインストールして解決できるか確認してください。それができない場合は、ユーザーに手助けを依頼してください。

2. リポジトリを設定する

対象となる各リポジトリで、gjalla を設定します。gjalla の完全なセットアップには、エージェント向けの指示ブロック、MCP サーバー、エージェントフックが含まれます。

gjalla setup

非対話型シェルでは、プロンプトなしの方法が使われます。エージェントを検出し、フックと MCP をインストールして、ガイダンスのセクションを書き込みます。「No coding agent detected」と表示された場合は、gjalla setup ensure --agent claude-code を実行してください（~/.codex/sessions が存在し、~/.claude/projects が存在しない場合は、代わりに --agent codex-cli を指定します）。サインインを求められますが、これはステップ3で行います。

3. サインインする（人間が行う唯一のステップ）

gjalla project list

成功した場合はサインイン済みです。ステップ4に進んでください。それ以外の場合：

gjalla auth login --no-browser --no-wait

表示された URL とコードをそのまま出力し、ユーザーに URL を開いて承認するよう依頼してください。処理が完了するまでツール呼び出しから出力が返されないため、ユーザーにコードが見えなくなります。処理をブロックする形式は実行しないでください。ユーザーから承認したと連絡があったとき、または少し待ってから、次を実行します。

gjalla auth status

終了コード 0 はサインイン済みを示します。続行してください。終了コード 3 は処理がまだ完了していないことを示します。URL とコードを再度表示し、もう一度依頼してください。終了コード 4 はコードの有効期限が切れたことを示します。ログインコマンドを再実行してください。それ以外のゼロ以外の終了コードの場合は、エラーを出力して停止してください。

4. プロジェクトをリンクする

gjalla sync

sync は、リポジトリの origin リモートから対応するプロジェクトを特定し、チームにプロジェクトがない場合は作成します。プロジェクト名はリポジトリ（owner/repo）に基づくため、origin が存在する場合は手動で作成せず、タイトルを勝手に付けないでください。結果に応じて、次のように対応します。

• AMBIGUOUS_TEAM（409）：表示されたチームをユーザーに提示し、ユーザーが指定したものを選んで gjalla sync --team-id <id> を再実行します。
• NO_ORIGIN：リポジトリ名の取得に使えるリモートがありません。作業ディレクトリや説明文ではなく、リポジトリのディレクトリ名を使います。gjalla project create -t "$(basename "$(git rev-parse --show-toplevel)")" を実行してください。
• それ以外のエラー：エラーを出力して停止してください。

5. 過去 7 日間のデータを補完する

目標：過去 7 日間に、このリポジトリでコーディングエージェントのセッションが行ったコミットごとに 1 件のレコードを作成し、そのセッションのトークン使用量とタスク種別ラベルを記録します。コミットが 5 件未満の場合は、1 度だけ対象期間を 30 日間に広げます。

使用しているハーネスがセッションのトランスクリプトを保存する場所はわかっているはずです（Claude Code：~/.claude/projects/。作業ディレクトリごとに 1 つのディレクトリがあります。Codex：~/.codex/sessions/）。このリポジトリに関係するトランスクリプトを探します。対象範囲に注意してください。親ディレクトリやこのリポジトリのサブディレクトリから実行されたセッションでも、コミットがこのリポジトリに反映されていれば対象です。ディレクトリ名ではなく、コミットを基準に判断してください。

各トランスクリプトについて：

• セッション ID はファイル名に含まれる UUID です。
• トランスクリプトには、実行した各 git commit と、その出力に含まれる [branch shortsha] が記録されています。これらを抽出し、git rev-parse --verify <short>^{commit} で拒否されたものは除外します。コミットがないセッションはスキップします。複数のトランスクリプトに同じ sha がある場合は、最初のものを採用します。
• 各コミットを feature、bug-fix、refactor、docs、test、chore のいずれか 1 つに分類します。Conventional Commits のプレフィックスがある場合はそれを使い、ない場合は git show -s --format='%s%n%b' <sha> とブランチ名から判断します。

各コミットを 1 度ずつ記録します。

gjalla attest add --commit <sha> --session <uuid> --task-type <type>

このコマンドは、セッションがどのエージェントに属するかを特定し、そのトランスクリプトからトークン数とモデルを読み取り、コミットの件名と作成日時を Git から取得して、すでに記録済みの sha はスキップします。セッションのトランスクリプトが見つからないというメッセージが表示された場合は、ID が間違っているか、このマシンにトランスクリプトがありません。次に進んでください。トランスクリプトにトークン数がないというメッセージが表示されても、そのコミットは対象に含めます。

記録したコミット数とセッション数をユーザーに伝え、マシンの外部に送信されるのはトークン数、タイムスタンプ、sha、ブランチ名、コミットの件名、タスク種別ラベルのみであることを説明してください。

6. アップロードしてレポートする

gjalla sync

同期によって新しいレコードがアップロードされると、下に支出の概要が表示されます。概要には、セッション数、コミット数、推定コスト、タスク種別ごとのコストと割合、最もコストの高いセッションとその成果物、価格を算出できなかったモデルが含まれます。gjalla spend show を実行すると、いつでも再度表示できます。gjalla spend show --json を実行すると、ペイロード全体が表示されます。オンボーディングが完了したら、ユーザーに概要を伝え、興味深い点も付け加えてください。コストのうちバグ修正に使われた割合、最もコストの高いセッションの目的、意外だった点などです。数値は自分で計算しないでください。

同期でエラーが報告された場合は、それを表示して終了してください。

7. 共有メモリを登録する

このステップの目的は 3 つ目の成果、つまりこのプロジェクトについて、チームメイトのエージェントがうっかり同じ問題を踏んで調べ直さなくて済むよう、知っておくべき事実をいくつか共有することです。

ユーザーが使っているハーネスの種類を問わず、エージェントがすでに学んだものの共有されていない情報から候補を集めます。たとえば：

• ~/.claude/projects/$ENC/memory/*.md（MEMORY.md はスキップ）
• ~/.codex/memories/*（存在する場合）
• CLAUDE.md、AGENTS.md、README.md のうち、gotcha、caveat、pitfall、note、troubleshooting を見出しとするセクション
• git log --since=30.days --format=%b | grep -iE 'because|gotcha|note:'

保存する内容と保存しない内容

共有メモリーとは、システムやチームの作業方法に関する、長期的に有用で自明ではない事実です。「ワーカーは API より先にデプロイする。そうしないと、マイグレーションが古いスキーマに対して実行される」「統合テストにはローカルスタックが必要。それがなくてもテストスイートは成功するが、何の証明にもならない」といった内容です。

候補のうち、保存してはいけないものが 2 種類あります。どちらも一見、有用に思えます。

プロジェクトではなく、個人に関する内容。 その人のエディター、シェル、好みの言い回し、作業時間、マシン上のパス、個人的に何を煩わしく感じるかなどです。これらは実際の情報であり、記録する価値もあります。ただし、チームではなく、その人自身のメモリーに保存するものです。別のチームメイトが作業に取りかかると事実でなくなるなら、それは個人的な情報です。

それ自体が秘密である値に関する内容。 有効期限切れに見えるもの、スコープが限定されたもの、偽物に見えるもの、ページ上で最も有用な情報である場合であっても、認証情報、トークン、キー、パスワード、接続文字列、その他アクセス権を与える値は決して記録しないでください。

2 つ目について重要なのは、秘密の「場所」と秘密そのものを区別することです。保存する価値があるのは、多くの場合、まさにその場所に関する事実です。

• 保存する：「分析サービスは GOOGLE_APPLICATION_CREDENTIALS から Vertex の認証情報を読み込みます。設定されていないと、すべてのモデル呼び出しが 403 で失敗し、クォータエラーのように見えます。」
• 決して保存しない：そのファイルの内容、またはファイル内のキー。

秘密を引用せずに事実を述べられない場合、その事実はメモリーではありません。削除し、見つけた場所に置いておくべきでない認証情報のように見えるなら、書き留めるのではなく、その旨をユーザーに伝えてください。

候補が微妙な場合は、含めないでください。

次に、保存する前に比較します

候補を主題ごとにまとめます。グループ内では、次のようにします。

• 同じことを述べる 2 つの文は重複です。より明確な方を残します。
• 同じ主題について異なることを主張する 2 つの文は矛盾です。好みでどちらかを選ばないでください。コードを少し確認すれば解決する場合は、コードが裏付ける方を保存します。それ以外の場合は、どちらも保存せず、出典の場所とともに両方を報告します。

タスクや TODO に関する内容、および gjalla memory show にすでにある内容は除外します。

残ったものを保存します。これらが長期的に有用なメモリーです。

gjalla memory add "<the fact>" -n "<short-name>" -c project

メモリーの状態を 1 行で報告します。候補数、除外した個人情報または機密情報の数、統合した重複の数、見つかった矛盾の数、保存した数を含めてください。次に、保存した事実を出力し、続けて「gjalla memory archive <key> で不要なものを削除してください。」と記します。

8. 検証して確認する

gjalla setup doctor

FAIL とマークされた行があれば、その修正方法とともに報告します。検出されたエージェントのガイダンスファイルに gjalla セクションがあることを確認します。興味深い知見をユーザーに強調して伝えたことも確認してください。これで完了です。