Knowledge & Reporting

2-Tier Knowledge System

ナレッジは2層に分かれ、プロジェクト固有の知見と組織横断の知見を分離管理する。

Tier 1: Project Knowledge

プロジェクト固有のナレッジ。各ロールの .knowledge/{role}.md に格納。

最大 15アイテム / ファイル
対象ロール: architect, developer, reviewer, designer, sre
サブエージェントが作業中に候補を報告
配置: Projects/{project}/docs/.knowledge/

Tier 2: Organization Knowledge

組織横断のナレッジ。2プロジェクト以上で確認されたパターンが昇格。

最大 20アイテム / ファイル
配置: knowledge/organization/
全プロジェクトのサブエージェント起動時に注入

組織ナレッジファイル一覧

File	Content
`process.md`	プロセス改善・ワークフロー知見
`architecture.md`	アーキテクチャパターン・技術選定知見
`development.md`	実装パターン・コーディング知見
`review.md`	レビュー観点・品質基準知見
`operations.md`	運用・デプロイ・インフラ知見
`pendulum-history.md`	振り子パターン履歴（過去の決定と揺り戻し記録）

昇格フロー

Tier 1

Project .knowledge/{role}.md

昇格判定

Critical 1-project / General 2-project

Tier 2

knowledge/organization/*.md

Knowledge Lifecycle

Read Protocol

📖

作業前に必ず読む

サブエージェントは作業開始前に、該当ロールのTier 1ナレッジ（プロジェクト）とTier 2ナレッジ（組織）を読み込む。これにより過去の失敗パターンの再発を防ぐ。

Write Rules

サブエージェントは作業中に「ナレッジ候補」を発見したら .knowledge/{role}.md に書き込む
候補がない場合も phase-state.yaml に knowledge_updated: [] を記録
Orchestratorの委譲チェックリストで書き込み漏れを防止

Promotion Timing

Type	Condition	Timing
Critical	1プロジェクトで発生した重大な問題	即座に昇格（改善レポート作成時）
General	2プロジェクト以上で確認されたパターン	遅延昇格（振り返り・監査時）

Capacity Management

各ナレッジファイルには上限がある。上限に達した場合、古い・解決済みのアイテムを整理してから追加する。

Tier 1: 最大 15アイテム / ファイル
Tier 2: 最大 20アイテム / ファイル

Pattern Tracker (tracker.yaml)

組織横断でパターンを追跡する。問題パターンと成功パターンの両方を記録し、改善の進捗を可視化する。

Problem Patterns

繰り返し発生する問題を追跡し、対策の効果を検証する。

yaml
problem_patterns:
  - id: "pp_001"
    description: "リンター設定の巻き戻し"
    count: 3
    state: "open"
    actions:
      - "guard.shにリンター設定変更の警告を追加"
      - "過去PR理由の検証ルールを追加"
    last_seen: "2026-03-30"

  - id: "pp_002"
    description: "dynamicParams変更による404"
    count: 2
    state: "resolved"
    actions:
      - "変更前に過去PRの理由を検証するルール追加"
    resolved_at: "2026-04-01"

Success Patterns

yaml
success_patterns:
  - id: "sp_001"
    description: "UI仕様を最初に全確定"
    count: 2
    benefit: "手戻りゼロで実装完了"

State Transitions

🔄

パターンの状態遷移

open → resolved（2回連続で再発なし） → reopened（再発時）

resolvedになっても再発すればreopenedに戻る。根本対策が有効かを継続的に検証する。

Improvement Reports

⚠

リアルタイム作成 -- Phase 9まで待たない

改善レポートは問題発覚時にOrchestratorがSecretaryを割り込み起動して即座に作成する。振り返りフェーズまで記憶に頼ると詳細が失われる。

作成トリガー

修正ループが 2回以上 発生
CO（Compliance Officer）が BLOCKED 判定
テスト失敗が発生
振り子パターンの検出

分析手法: 5-Why Analysis

表面的な対症療法ではなく、根本原因に到達するまで「なぜ？」を繰り返す。

出力

Secretaryが Report/Improvement/YYYY-MM-DD_{topic}.md を作成
ナレッジ昇格が必要な場合は改善レポート作成と同時に実行
tracker.yamlのproblem_patternsも同時に更新

Memo System (memo.md)

セッション中の作業メモを随時記録するファイル。

配置: Report/__memo__.md
セッション中に随時更新（Orchestrator完了後にSession Managerが追記）
実施内容、トークン使用量、気づきなどを記録
デイリー本番記作成後にクリアされる
Hook（post-agent-checklist.sh）により更新が強制される

Token Usage Tracking (token-usage.yaml)

全エージェントのトークン消費を記録し、コスト管理と最適化に活用する。

yaml
sessions:
  - session_id: "session_2026-04-01_001"
    agents:
      - role: "orchestrator"
        model: "sonnet"
        group: "Group 1"
        tokens: 24500
        timestamp: "2026-04-01T10:30:00"
      - role: "session-manager"
        model: "haiku"
        group: "session_start"
        tokens: 8200
        timestamp: "2026-04-01T10:00:00"

全エージェント起動がトークン記録対象（Orchestrator、Session Manager、Explore等）
日次集計でコスト傾向を把握
Hook（pre-agent-compliance.sh）により記録漏れをブロック

Daily Report

その日の最終セッションでSecretaryが作成するデイリー本番記。

データソース

Source	Content
`__memo__.md`	セッション中の作業メモ
`token-usage.yaml`	トークン消費データ
`tracker.yaml`	パターン追跡データ
`Improvement/*.md`	改善レポート
`phase-state.yaml`	各タスクの進捗状態

本番記セクション

Summary -- 日次サマリー
Task Table -- タスク一覧と進捗
Good Points -- うまくいったこと
Issues -- 問題・課題
Quality Metrics -- 品質指標
Tokens -- トークン消費集計
Compliance -- プロセス遵守状況
Next Actions -- 翌日のアクション

Report File Structure

Report/ ├── __memo__.md -- セッション中の随時メモ（本番記後クリア） ├── token-usage.yaml -- トークン消費記録 ├── Daily/ │ └── YYYY-MM-DD.md -- デイリー本番記 ├── Improvement/ │ └── YYYY-MM-DD_{topic}.md -- 改善レポート（リアルタイム作成） └── Projects/ └── {project}/ └── YYYY-MM-DD.md -- プロジェクト別デイリー