agent-pulse

Agent Pulse

Agent Pulse はニュースアグリゲーターではなく、証拠に基づくインテリジェンスシステムとして運用してください。事実、証拠、コンテキスト、影響、判断、次のシグナルを区別し、公開するすべての主張を、許可されたソースの証拠までたどれるようにしてください。

このスキルを使う場面

• ユーザーが Agent Pulse をローカルで実行する、リポジトリーのスナップショットを更新する、または Control Room と公開サイトを確認する場合。
• ユーザーがデータソースの追加、分類、テスト、有効化、劣化、隔離、または廃止を必要としている場合。
• ユーザーがシグナルの収集、Event の重複排除やクラスタリング、ソースの健全性監査、またはシステム機能の評価を依頼する場合。
• ユーザーがナラティブ、週次ブリーフ、Scout の機会、またはプライバシーに配慮した静的エクスポートを求める場合。
• ユーザーがコレクター、スキーマ、ランキング、公開ゲート、ソースのライフサイクル、または公開用 DTO を変更する場合。
• 一般的な Web スクレイピングや調査ではなく、Agent Pulse 自体がタスクの対象である場合。

手順

ステップ 1：作業パケットを記録する

依頼された成果、対象となるプレーン、証拠の境界、検証目標を記録します。

• 成果：運用、調査、コード／スキーマの変更、データの更新、公開、または調査。
• プレーン：サーバー専用の Control Room／データベース、収集パイプライン、または公開用静的エクスポート。
• 対象：Source、SourceRun、Signal、Event、Track、Actor、Resource、View、Job、または Scout の機会。
• 証拠：主要な URL または論文、ソースのティア、出所、鮮度、不確実性。
• 範囲：単一のソース、対象となるバッチ、すべてのソース、ナラティブ、またはリリース。
• 検証：対象を絞ったテスト、npm run check、エクスポートの検証、プライバシースキャン、またはブラウザーのスモークテスト。

依頼が曖昧な場合は、公開に関する判断をでっち上げないでください。不足している対象を確認するか、保留の理由を明記したうえで、項目をレビュー／ドラフトの状態にしてください。

ステップ 2：編集前にプロジェクトの規約を読む

Agent Pulse リポジトリーのルートから、まず AGENTS.md と関連するドキュメント／仕様を読みます。収集や公開に関わる作業では、最低限 docs/ARCHITECTURE.md、docs/SOURCES.md、docs/LEGAL.md を確認してください。ソース固有の例外を独自に設けず、既存のモジュール境界に従ってください。

• src/collectors/ は SourceAdapter の契約、フェッチの安全性、アダプターを担当します。
• src/domain/ は URL、クラスタリング、スコアリングの純粋なルールを担当します。
• src/db/ は Kysely のスキーマ、マイグレーション、リポジトリー、シードカタログを担当します。
• src/pipeline/ は収集、クラスタリング、評価、Scout、エクスポートのオーケストレーションを担当します。
• src/server/ は公開／管理 API とセキュリティヘッダーを担当します。
• web/public/ はフレームワークに依存しない静的インテリジェンスサイトです。web/admin/ は非公開です。
• tests/ にはユニットテストと SQLite 統合テストがあります。

スキーマ、ソースのライフサイクル、ランキング、公開、または Scout の変更では、対応する仕様をドキュメント先行で扱い、コード、テスト、ユーザー向けの変更履歴をまとめて更新してください。

Step 3: 最も範囲の狭い運用レーンを選ぶ

既存の npm スクリプトを使用し、独立した操作は分けて実行してください。

必要な操作	開始コマンド	ガードレール
ローカルアプリのインストール／起動	npm install; cp .env.example .env; npm run dev	.env や認証情報をコミットしないでください
ローカル SQLite のシード投入／マイグレーション	npm run db:seed または npm run db:migrate	より新しいローカルの証跡を保持してください
収集とクラスタリング	npm run collect	デフォルトでは対象条件を満たすソースを使用し、失敗を分離してください
収集範囲の指定	npm run collect -- --scope=eligible または --scope=all	単一のソースには --source=<id> を使用してください。--backfill は意図的な場合にのみ使用してください
ソースの健全性	npm run sources:audit	非破壊的に実行し、劣化・失敗・スキップの証跡を記録してください
システムの機能	npm run evaluate:system	リグレッションを確認する際は、ベースラインと比較してください
運用の照合	npm run ops:reconcile	スキーマやランキングルールを暗黙的に変更しないでください
Scout の仮説	npm run scout:generate -- 3	上限は 1～18 です。Scout は事実として公開するものではありません
静的な公開	npm run export の後に npm run public:validate	許可リストに登録された公開用 DTO のみをエクスポートしてください
マージ／リリースの検証	npm run check	lint、typecheck、テスト、エクスポート、公開検証を含める必要があります

コードを変更する場合は、まず対象を絞った最小限のテストまたはコマンドを実行し、完了を報告する前に npm run check を実行してください。データを更新する場合は、更新前後の件数、ソース実行の状態、 出力アーティファクトまたはレポートのパスを記録してください。

Step 4: 証跡とソースの境界を徹底する

• 公式 API、RSS/Atom、GitHub Releases、論文、提出書類、その他の安定した公開ソースを優先してください。
• Tier 1 は一次事実、Tier 2 は専門家による検証、Tier 3 は専門家の解釈、Tier 4 は拡散の勢いです。アグリゲーターは発見や話題性を測るセンサーとして使用し、事実を裏付ける唯一の証拠としては決して使用しないでください。
• 信頼度（事実の正確性）と話題性（拡散度）は分けてください。手入力のスコアを測定済みのリーチとして扱わないでください。
• 公開イベントにはクリック可能な元ソースが必要です。通常は Tier 1 のソースを 1 件、または独立した Tier 2 のソースを 2 件必要とします。例外には未検証のマークを付けてください。
• robots、ライセンス、利用規約、レート制限、キャッシュ、ソースの割り当てを遵守してください。ログイン、WAF、CAPTCHA、ペイウォール、プラットフォームの制限を回避しないでください。ブラウザーによるスクレイピングが実際の作業である場合は、scrapling を使用してください。
• タイムアウト、再試行、バックオフ、リダイレクト、レスポンスサイズ、並行処理に上限を設けてください。リダイレクト先を再確認して SSRF を防ぎ、ループバック、リンクローカル、プライベート、認証情報を含む、または DNS リバインディングのおそれがある URL を拒否してください。
• 第三者の記事全体ではなく、出所情報と上限を設けたメタデータを保存してください。ソースが廃止された場合も、過去の出所情報を保持してください。

Step 5: 公開とプライバシーのゲートを明確にする

自動収集されたオブジェクトは、すべての決定論的なゲートを満たさない限り review に入ります。 事実と解釈を分け、不確実性を明示してください。LLM によるエンリッチメントでインサイトの草案を作成できますが、 証跡にたどれる必要があり、スキーマ、証拠、準備状況、競合、公開の各ゲートを迂回することはできません。

エクスポートの前に、公開出力に許可リストに登録された DTO だけが含まれ、データベース、トークン、 認証情報、生のペイロード、プロキシ設定、ローカルパス、管理者用フィールド、非公開メモが含まれていないことを確認してください。 プロセスが正常終了しても、それだけでは証明になりません。検証出力、生成されたアーティファクト、またはテスト結果を提示してください。

Step 6: 監査可能な引き継ぎとして結果を報告する

簡潔な報告に、次の内容を含めてください。

1. 要求されたレーンと範囲；
2. 変更したファイル、ソース、またはコマンド；
3. 証跡と出所情報の状態；
4. 該当する場合は、変更前後の件数／状態；
5. 検証コマンドと実際の結果；
6. 残る不確実性、劣化したソース、ブロック中のゲート、次のシグナル。

キュレーション済みのシード／デモ用データセットを、本番品質の継続的な検出と呼ばないでください。また、実験中または計画中の機能を、リリース済みと説明しないでください。

例

例 1：利用可能なソースを更新する

npm run collect -- --scope=eligible を実行し、JSON の収集／クラスタリング結果を確認して、ソースの失敗と、作成、関連付け、または保留された Event を分けて報告します。収集に成功したという理由だけで、レビュー対象の Event を昇格させてはいけません。

例 2：新しいソースアダプターを追加する

ソース仕様と法務仕様を読み、SourceAdapter の境界を拡張し、機能メタデータ、フィクスチャのカバレッジ、成功／失敗／劣化のテスト、ライフサイクル／来歴の処理を追加します。対象を絞ったコントラクトテストを実行してから npm run check を実行します。実際の観測期間とコンプライアンスチェックを通過するまでは、新しいソースを draft または shadow のままにします。

例 3：Scout の機会を公開する

トリガーとなった Event と証拠を確認してから、範囲を限定した Scout コマンドを実行します。結果は、対象ユーザー、今である理由、コンセンサスに反する洞察、最初の小さな実験、リスク、無効化条件を含む、明確に仮説と示されたものとして提示します。事実、投資判断、または外部アクションとして提示してはいけません。

例 4：公開リリースを検証する

npm run export に続けて npm run public:validate を実行し、生成された公開フィンガープリントまたはレポートを確認します。非公開のコントロールプレーンデータが含まれていないことを確認し、リリースを準備完了として報告する前に、各重要な Event を公開証拠にリンクします。

ベストプラクティス

1. ソース固有の近道よりも、既存のコントラクトと小さく元に戻せる差分を優先します。
2. すべての報告で、カタログ登録済み、観測済み、有効、公開済みの状態を分けます。
3. ソースの失敗は個別の健全性状態として扱い、バッチ全体を破棄する理由にしません。
4. ローカルのデフォルト動作には SQLite を使用します。実際の統合カバレッジがない場合、MySQL をサポートしていると主張してはいけません。
5. ユーザーに見える変更について、変更履歴と公開向け製品変更履歴のデータを同期させます。
6. 生の証拠の境界を保持し、非公開の運用データを GitHub Pages に決して含めません。
7. 永続的な各判断について、何がそれを強め、弱め、または無効化するかを記録します。

参考資料

• Agent Pulse リポジトリ
• アーキテクチャとデータフロー
• データソース、ティア、取得ポリシー
• 責任ある使用と法的境界
• 機能マップ
• ローカルコマンドと境界のマトリクス