proglens.yaml と .proglens/

progLens が開くのは、最上位に proglens.yaml があるフォルダです。解説はすべて人が読めるテキスト（YAML と Markdown）で、.proglens/ の下に置きます。

解説ファイルを書くのは progLens の書き込み層だけです。AI は MCP の道具（MCP サーバー）で、人はアプリの操作で書きます。手で直接書き換えると、同時に書いた人の変更を上書きしたり、形の崩れた解説が残ったりするので、Claude Code のプラグインのガードが直接の編集を止めます。

置き場の形

<プロジェクト>/
├── proglens.yaml                # マニフェスト（このファイルのあるフォルダをプロジェクトとして開く）
└── .proglens/
    ├── notes/                   # ノート。ソースのパスの鏡写し: src/app/page.tsx → notes/src/app/page.tsx.md
    ├── tours/                   # ツアー（AI が提案する読む順番）
    ├── trails/                  # データ 1 件の旅
    ├── perspectives/            # 視点
    ├── paths/                   # 学びの道筋
    ├── figures/                 # 動く図（箱・矢印・群れ・場面のデータ）
    ├── cache/                   # 機械が抽出した事実と索引（git に入れない）
    └── local/                   # 自分だけのもの（git に入れない）
        ├── reviews/             # レビューのスレッド
        ├── baselines/           # 人が最後に確かめた版のノートの控え（解説の差分の基準）
        ├── shots/               # 実画面の強調の画像
        ├── exports/             # 客向けの視点の書き出し
        ├── understanding.yaml   # 理解の印
        └── checks/              # 確認の質問と答え

機械で分かる事実（関数の一覧・どこから使われているか）は解説ファイルに書かず、cache/ に置きます。解説ファイルには、人と AI にしか書けないこと（意図・役割・つながりの理由）だけを書きます。

マニフェスト

schemaVersion: 0
project:
  name: todo-app
  summary: Supabase を使う Todo 管理の Next.js アプリ   # 1 行。ツアーの入口に出る
adapters: [web-ts]            # 任意: 使う強化の層。省くと自動で決める。generic は常に効く
exclude:                      # 網羅率の母数から外す（理由は必須）
  - { glob: "public/**/*.png", why: 画像素材 }
rules:                        # glob で役割を一括で付ける（網羅率では「規則で分類」）
  - { glob: "components/ui/**", role: vendored-ui, note: 取り込んだ汎用の部品。中身は読まなくてよい }
  - { glob: "package-lock.json", role: lockfile, note: 依存の固定 }
lanes: [input, type, state, api, server, db, display]   # 任意: データの旅の段の名前

テストや設定のように似たファイルは、1 つずつノートを書かずに rules で役割をまとめて付けられます。

ノート

ノートは 1 つのソースファイルに 1 つで、フロントマター（構造）と本文（自由な Markdown）でできています。

---
schema: proglens/note@0
file: src/app/todos/actions.ts
fingerprint: sha256:9f2c…       # AI がこの解説を書いたときのファイルの指紋
role: server-action             # 役割
summary: Todo の作成・更新を受け付ける Server Action 群
symbols:                        # 関数やクラスごとの解説（任意）
  "createTodo().":
    summary: フォームの内容を検証して todos に 1 行追加する
review:                         # 人の確認。アプリだけが書く
  state: reviewed
---
## このファイルの役割
（自由な Markdown。見出し・表・コードブロックが使える）

AI の解説（fingerprint）と人の確認（review）を分けて持ちます。コードが変わると、「AI の解説が古い」「人の確認が古い」を別々に出せます
型で追えない継ぎ目（フォームの name と FormData のキーなど）は、edges に「AI が書いたつながり」として残せます
本文は 1 ノート 64 KB まで。React の基本のような一般的な説明は、ノートごとに書かず、パックの知識（概念の解説）を参照します

内置きと外置き

	内置き	外置き
置き場	プロジェクトのフォルダの中	プロジェクトの外（既定は `~/.proglens/lenses/<名前>`）
プロジェクトに書くもの	`proglens.yaml`・`.proglens/`・`.gitignore` の 2 行（`.proglens/cache/` と `.proglens/local/`）	何も書きません
マニフェスト	上の形	上の形に `target`（対象のリポジトリのパス。絶対パスは書かない）を足す
向いているもの	自分の private なリポジトリ。解説を git で共有できる	公開のリポジトリ・他人のリポジトリ

ノートのパスや網羅率の母数は、どちらでも対象のリポジトリの根からの相対です。外置きの置き場にはコードの引用が入るので、公開しないでください（private な git か手元のフォルダに置きます）。どのフォルダをどの外置きで読むかは PC ごとに ~/.proglens/lenses.json に覚えます。

パック（言語ごとの強化）

解析はパックで言語ごとに強くできます。パックは構文のクエリ・規則・知識・読み方のひな形といったデータだけで、中から任意のコマンドやコードは実行しません。

パック	効くもの
generic（土台・常に効く）	どの言語でも網羅率・役割の推定・関数やクラスの輪郭。tree-sitter で C・C++・Dart・Go・JavaScript・Python・Rust・Swift・TypeScript の構文を読みます
web-ts	TypeScript・React・Next.js・Supabase・zod。型の辺・Server Action・Route Handler・マイグレーションの SQL・画面の部品と遷移
rust	`Cargo.toml` のクレートと依存・`mod` の木・`use` の行き先

作者のサイト（takushio2525.com） progLens のデータの扱いプライバシーポリシー Cookie 設定