agentic-productivity-setup

エージェントによる生産性向上の設定

AI エージェントによって、人の成果が時間の経過とともに向上するかを測定する、決定論的なシステムを構築します。データ収集はローカルで行います。毎朝、集計グラフを正確に3つ含む非公開の Discord レポートを1件送信します。

プライバシーに関するルール

以下は必須要件として扱ってください。

1. 新規に実装してください。別のインストール環境、ランタイムデータベース、ログ、セッションストア、認証情報、マシン上のパス、リポジトリ一覧、非公開の設定をコピーしてはいけません。
2. プロンプトのテキスト、応答、ツールの出力、リポジトリ名、ファイルパス、個人情報、生のセッション ID、コミットメッセージを保存または送信してはいけません。
3. ネイティブのエージェントストアはイベント数の集計に限って読み取ってください。一時的な識別子はメモリ内に保持した後、破棄してください。コレクターが実行間のベースラインを必要とする場合に限り、一方向ハッシュを保存してください。
4. グラフはデフォルトでローカルに描画してください。日次の合計値とグラフ画像を送信する先は Discord のみにしてください。任意のリモートグラフサービスを有効にする前に、データの流れを正確に説明してください。
5. Discord Webhook は、現在のユーザーの macOS Keychain に保存してください。ソースコード、コマンド引数、環境ファイル、データベース、ログ、テスト、スケジューラー定義に含めてはいけません。
6. テストでは合成フィクスチャを使用してください。コピーしたセッションデータ、実際のプロンプト、実際のリポジトリメタデータ、実際の認証情報を使用してはいけません。
7. ネイティブデータベースは読み取り専用で開いてください。コレクターがエージェントの状態を変更してはいけません。
8. ソースが見つからない、読み取れない、または未対応の場合は、カバレッジの問題として報告してください。収集に失敗しても、暗黙的にゼロとして扱ってはいけません。

スコープの確認

まず、ユーザーが求めているのが説明、新規プロジェクト、インストールのどれかを確認してください。仕組みについて尋ねているだけの場合は、何も作成またはインストールしないでください。

構築する場合は、以下の値を確認するか、安全なデフォルト値を設定してください。

• プラットフォーム：macOS。他のオペレーティングシステム向けに設計を変更する場合は、事前に確認してください。
• コードルート：$HOME/code。
• タイムゾーン：Mac に設定されているタイムゾーン。
• レポート時刻：現地時間の08:00。
• レポート期間：昨日までの90日間。
• エージェントのハーネス：測定対象としてユーザーが希望するツールのみ。
• プロジェクトの場所と、逆引き DNS 形式の LaunchAgent ラベル。

Webhook をチャットに貼り付けるようユーザーに求めてはいけません。アプリケーションの構築後、安全なターミナル入力で設定してください。

メトリクスの定義、保存範囲、レポートの送信先、または Mac 外部に送信するデータを変更する前に確認してください。重要な選択は、生成したプロジェクト内の短い ADR に記録してください。

アーキテクチャ

以下のデータフローを使用してください。

Git reflogs + native agent registries
    -> read-only collectors
    -> daily aggregate counts
    -> local SQLite database
    -> local chart renderer
    -> one Discord webhook request

ソースチェックアウトとインストール済みランタイムを分離してください。

• アプリケーションコードを ~/Library/Application Support/<app>/app/ にコピーします。
• 集計状態は、その隣の metrics.sqlite3 に保存します。
• ログは ~/Library/Logs/<app>/ に保存します。
• plist を ~/Library/LaunchAgents/ にインストールします。
• ディレクトリのモードは 0700、機密ファイルのモードは 0600 にします。
• 再インストールや通常のアンインストール後も、集計状態を保持します。

メトリクスの契約

独立した3つのメトリクスを実装してください。統合された生産性スコアは作成しないでください。

一意なローカルコミット数

• 設定済みのコードルート以下を再帰的に検索し、Git リポジトリを検出します。
• Git の共通ディレクトリを基準に、プライマリチェックアウトとリンクされたワークツリーを重複排除します。
• 指定された日付範囲について、reflog からローカルでの作成イベントを読み取ります。
• そのリポジトリで設定された ID のメールアドレスと、作成者またはコミッターのメールアドレスが一致するコミットのみを含めます。
• すべての参照とワークツリーを通じて、各コミットハッシュを1回だけ数えます。
• フェッチされたコミット、プッシュ、ブランチの移動だけによるイベントは除外します。
• ハッシュはメモリ内にのみ保持します。最終的な日次件数を保存します。

アクティブなエージェントセッション数

• ネイティブレジストリにアクティビティが記録された各ローカル暦日について、セッションを1件として数えます。
• GUI、CLI、ヘッドレス、再開済み、親、サブエージェント、委任、自動化されたセッションを含めます。
• ハーネスのネイティブなセッション ID をメモリ内で使って重複排除します。
• ストレージとレポートでは、各ハーネスを個別に扱います。

指示を含むプロンプト

• 指示を含む、保存されたユーザー、システム、および開発者の入力をカウントします。
• 人間のプロンプト、自動化、セットアップコンテキスト、委任、およびサブエージェントの指示を含めます。
• アシスタントの応答、ツールの結果、空の入力、および重複した保存コピーは除外します。
• イベントを分類するのに必要な長さだけコンテンツを検査します。決して保存またはログに記録しないでください。

日付を割り当てる前に、すべてのタイムスタンプを設定されたタイムゾーンに変換してください。

コレクターの設計

ハーネスごとに1つのアダプターを使用します。プロセスの検査、シェル履歴、ウィンドウタイトル、または推測されたファイルタイムスタンプよりも、ネイティブレジストリを優先してください。

一般的なソース形状をサポートします:

• JSON または JSONL のセッション記録。
• 読み取り専用の SQLite レジストリ。
• エディタのグローバルまたはワークスペースの状態データベース。
• 読み取り可能なローカルレジストリが存在しない場合の、認証済みネイティブ CLI エクスポート。

各アダプターは次を返す必要があります:

• メモリ内の日次の一意なセッション識別子。
• 日次のプロンプト数。
• full、partial、unavailable、absent、または error のカバレッジ。
• カウントと制限事項を含む短い詳細文字列。決してプライベートデータを含めないでください。

一部のストアはセッション合計を公開しますが、各ターンのタイムスタンプは公開しません。そのようなストアでは、ハッシュ化されたソースキーと合計を保存し、ローカルベースライン以降に観測された正の差分のみを帰属させます。古い帰属は partial としてマークしてください。

インストールされているハーネスを実行時に検出します。サポートされていないツールは、ゼロアクティビティとして誤ってラベル付けするのではなく、チャートから absent のままにしてください。

集約データベース

WAL モードの SQLite を使用します。スキーマは小さく保ちます:

• daily_metrics: day、metric、harness、count、collection time。
• collector_health: ハーネスごとのインストールおよびカバレッジ状態。
• source_snapshots: ハッシュ化されたソースキー、最後の合計、観測時刻。
• collector_baselines: ハーネスごとの最初の信頼できる観測。
• deliveries: レポート日、送信状態、送信時刻、および短い安全なエラー。

日次カウントには単調な upsert を使用します。後で行われる不完全なスキャンが、すでに保存されているより高い値を消してはなりません。

生のイベント、メッセージ、プロンプト、応答、リポジトリ名、パス、または識別子のためのテーブルを決して作成しないでください。

レポートと Discord 配信

選択したウィンドウに対して正確に3つのチャートを作成します:

1. 日次の一意なコミットを折れ線および面グラフとして。
2. 日次のアクティブセッションをハーネス別に分割した積み上げ棒グラフとして。
3. 日次の指示プロンプトをハーネス別に分割した積み上げ棒グラフとして。

各チャートに、通常の最小二乗法による直線のトレンドラインを追加します。セッションとプロンプトのトレンドラインには、日次の合計を組み合わせて使用します。固定されたチャート依存関係を使用して、PNG ファイルをローカルでレンダリングします。ネットワークレンダラーに暗黙的にフォールバックしないでください。

Discord メッセージには次のもののみを含める必要があります:

• レポート日。
• 昨日の3つの合計。
• 短いコレクターカバレッジの概要。
• 3つの PNG 添付ファイル。

1回のマルチパート POST を送信します。許可されるメンションを無効にします。有効な Discord webhook ホストのみを受け入れます。短いタイムアウトを使用します。リクエスト URL またはボディを決してログに記録しないでください。

ネットワーク処理の前に、SQLite でレポート日を確保します。成功した Discord 応答の後にのみ、送信済みとしてマークします。通常の実行は、レポート日ごとに1回送信する必要があります。再送信には明示的な強制オプションを必須とします。

スケジューリング

ユーザー LaunchAgent を使用します。スケジュールで LLM を実行しないでください。

設定:

• 選択した日次レポート時刻の StartCalendarInterval。
• コレクターがプロンプト差分を必要とする場合の StartInterval 300 秒。
• ログインおよびスリープ復帰のキャッチアップのための RunAtLoad。
• ProcessType を Background に設定。
• LowPriorityIO を有効化。
• 制限的な 077 umask。plist では10進数の 63 として表現します。
• プライベートログディレクトリ内の stdout および stderr パス。

すべてのインターバルで差分のみのソースを観測する場合があります。レポート時刻より前は、そのローカル観測の後に停止します。レポート時刻以降は、昨日を収集し、完全なウィンドウを構築し、その日がまだ送信済みとしてマークされていない場合にのみ送信します。

インストーラーは、絶対ランタイムパスを plist にレンダリングし、plutil で検証し、既存のジョブを安全に置き換え、起動する必要があります。認証情報は plist に含めないでください。

プロジェクト構成

小規模で読みやすいプロジェクトにします。

agentic_productivity/
  cli.py
  collectors.py
  database.py
  model.py
  reporting.py
bin/
  agentic-productivity
launchd/
  <label>.plist.in
scripts/
  install.sh
  uninstall.sh
  test.sh
tests/
docs/adr/

ユーザーが別のシンプルで保守しやすいスタックを選ばない限り、Python 3.11 以降を使用します。コレクターはモジュール化します。スケジュール実行するコマンドは、決定論的かつ非対話型にします。

次のコマンドを用意します。

• doctor：前提条件、パス、認証情報の有無、データベース、コレクターの対応範囲を、秘密情報を漏らさずに確認します。
• collect：配信せずに集計データを収集して保存します。
• mock：ネットワークに接続せず、配信状態も変更せずに、収集、レポート作成、グラフの描画、複数パートの組み立てを実行します。
• run：スケジュールされた観測と冪等なレポートを実行します。
• status：収集と配信の安全な状態を表示します。
• configure-webhook：標準入力から Webhook を読み取り、macOS Keychain に保存します。

Webhook の安全な設定

実装後は、次のような対話型シェルのパターンを使用します。

read -r -s REPORT_WEBHOOK
printf '%s\n' "$REPORT_WEBHOOK" | ./bin/agentic-productivity configure-webhook
unset REPORT_WEBHOOK

コマンドが出力するのは、設定が成功したかどうかだけにしてください。秘密情報をエコーしてはいけません。

検証ゲート

すべてのチェックに合格するまで、成功を報告しないでください。

1. 合成したネイティブストアのフィクスチャを使って、すべてのコレクターをテストします。
2. 重複排除、タイムゾーンの境界、プロンプトのロールによるフィルタリング、単調なアップサート、カバレッジの失敗、冪等な配信をテストします。
3. レポートに含まれるのが集計データのみで、添付ファイルがちょうど 3 つであることをテストします。
4. テストスイート全体と、ネットワークに接続しない mock コマンドを実行します。
5. まず一時的なホームディレクトリにインストールします。実行にソースチェックアウトやランタイム状態が不要であることを確認します。
6. レンダリングされた plist に認証情報や非公開のソースデータが含まれていないことを確認します。
7. トラッキング対象のファイルに、データベース、ログ、セッションのエクスポート、プロンプトのフィクスチャ、認証情報、マシン固有の絶対パス、実在する個人情報が含まれていないことを確認します。
8. doctor を実行し、LaunchAgent を読み込んで、最後の終了ステータスが 0 であることを確認します。
9. ライブテストレポートの送信は、ユーザーの許可を得た場合に限ります。

プライバシーに関するチェックに少しでも不確かな点があれば、そのファイルのリリースを中止します。チェックを弱めてはいけません。

完了レポート

ユーザーには次の内容を伝えます。

• ソース、インストール済みアプリ、集計データベース、plist、ログの保存場所。
• 有効になっているメトリクスとハーネス。
• タイムゾーン、レポート時刻、対象期間。
• Webhook が設定されているかどうか。Webhook 自体は表示しません。
• 実行したテストと、LaunchAgent が正常に動作しているかどうか。
• 現在も重要な、部分的または利用できないコレクターすべて。