Looptrack 利用者ガイド
Looptrack は AI コーディングエージェントの外部記憶になるイシュー管理ツールで、ループエンジニアリングを実際に回すための道具です。 記録するのは AI が分解した作業単位の課題で、プロジェクト本来のイシューとは別のものです。AI の作業計画と意思決定が見えるようになります。作業ごとのトークンも残るので分析レポートまで出せます。 コーディング AI と人が同じイシューを軸に作業を回します。それが基本の形です。
このガイドは使う人向けです。 サーバの設計や配置の細かい話は開発者・運用者向けの文書に回しました。
English: ../README.md
このガイドはリリースの版ごとに Web でも読めます。入口は https://howashoji.github.io/Looptrack/latest/ja/ です。 動いている版に合わせて読むときは https://howashoji.github.io/Looptrack/<版>/ja/ を開いてください。1.0.1 なら v1.0.1/ja/ です。
版の選び方
Looptrack にはデスクトップ版とサーバ版があります。違うのはインストールから AI エージェントとの接続までで、その先は共通です。
| 版 | 向いている場面 | 入口 |
|---|---|---|
| デスクトップ版 | 1 台の PC を 1 人で、ターミナルなしで使う。ダブルクリックで起動し、ブラウザでセットアップを仕上げ、AI とは会話で接続します | デスクトップ版 |
| サーバ版 | 複数の人で共有するサーバや、端末から使う自分だけのサーバ。looptrack setup か install.sh で立ち上げます | サーバ版 |
1 台の PC を 1 人で、ターミナルなしで使う場合はデスクトップ版を選んでください。
共通の節
次の節はどちらの版にも当てはまります。
| # | 節 | 内容 |
|---|---|---|
| 1 | 概念 | ループエンジニアリングとは何か・なぜイシューを正本にするのか |
| 2 | 本システムの位置 | 3 層のループのどこに、どの機能が当たるか |
| 3 | 日々の使い方 | 最初の 1 周・起票・受け入れ条件・検証コマンド・コメントの型・担当者・表示の言語 |
| 4 | AI ごとの手引き | Claude Code・Codex・GitHub Copilot・その他の AI |
| 5 | FAQ / トラブルシュート | よくある表示とその対処 |
| 6 | トークンレポート | 何が記録され何が送られないか・イシューへの帰属・PDF のレポートの作り方と台帳 |
初めてなら 1 を読んでから自分の版の始め方へ進み、その後に 3 を読んでください。
用語
| 用語 | 意味 |
|---|---|
| サーバ | イシューを保存する looptrack serve です。ブラウザの画面・REST API・MCP を持ちます |
| CLI | 手元で動く looptrack です。looptrack issue … でイシューを操作します。サーバと CLI は同じ実行ファイルです |
| プロジェクト | イシューの入れ物です。slug（例 demo）と ID の接頭辞（例 DEMO → DEMO-0001）を持ちます |
| MCP | AI がツールとしてサーバを呼ぶための接続です。AI は CLI か MCP のどちらかでイシューを操作します |
| hook | AI のセッションの開始・ツールの実行後・停止といった決まった時点で動く小さな処理です |
| kit | 各プロジェクトに入れる hook・規則文・skill の一式です。必ず入る core と、選んで入れる loop があります |
開発者・運用者向けの文書
- README: リポジトリの全体
- docs/server/DEPLOY.md: 配置と
looptrack setupの詳細 - docs/server/DESIGN.md: 設計