プロジェクト論理マップ は何をしますか？
メンテナーとAIが「何を変更するか、どこに影響するか、何を壊してはいけないか、どう検証するか」を答えられるようにします。
タスク範囲の選択
- 初回生成: 要件とコードベースのフォレンジックから、Markdown 関係マップを生成します。視覚的な閲覧が必要な場合や既に HTML がある場合は、同時に視覚図を生成またはメンテナンスします。
- 差分更新: 安定したIDを保持し、変更された事実、関連、ステータス、図のみを更新します。削除されたノードへの参照をチェックします。
- 影響分析: 特定の変更を中心に、入力、コンシューマ、状態、例外分岐、制約、検証を追跡します。ユーザーが分析のみを求める場合、変更は実施しません。
既存のプロジェクトファイルとIDを優先します。新規プロジェクトでは、デフォルトで docs/LOGIC_MAP.md を出力し、ビジュアル版はデフォルトで docs/logic-map.html を出力します。既存の命名規則やユーザー指定の場所があればそれを優先します。
フォレンジックの後、関係を構築する
プロジェクトの規約、要件ベースライン、主要なエントリポイント、ページ/ワークスペース、状態とストレージ、ビジネスフロー、テスト、リリース記録を読み取ります。コアユーザータスクに沿って必要なコードを読み取り、リポジトリをファイル単位で網羅する必要はありません。
以下を明確に区別します: 要件の約束、実際の実装、自動検査の証拠、実行環境の検証、外部監査。古い記録には日付と証拠範囲を記録します。未実行のチェックを合格と記載してはいけません。
重点的に追跡する項目:
- 複数のエントリポイントが実際に同じ処理チェーンを共有しているか、特定のステップをバイパスしているか。
- データを誰が作成し、保持し、消費し、上書きし、解放するか。永続化されるか、マシンを離れるか。
- キャンセル、空データ、拒否、制限超過、パース失敗がそれぞれどのように終了するか。
- 高頻度更新、バッチ、しきい値などがプロジェクト固有の不変条件を担っているか。
ドキュメントとコードの矛盾を発見した場合は、それぞれを記録し、見栄えのために強引に統合しません。コードにリスクを発見した場合はギャップとして書き込むことができますが、タスクを自動的に修正に拡大しません。
トレーサブルなモデルを構築する
references/model.md を読み、そのノード、関係、証拠フィールドを採用します。プロジェクトの既存IDを使って簡略化・調整します。
まずコアタスクの一文定義とメインチェーンを書き、その後で正常/異常分岐、ページ間状態、インターフェース、制約、検証を補います。図上で隣接していることは関係があることを意味しません。すべてのエッジはその意味と根拠を説明できなければなりません。
デフォルトの納品構造:
- 機能概要: 読者が最初に製品のできることを把握できるようにします。実際のユーザータスクでグループ化し、技術的な分割図の数を機能の数として扱ってはいけません。また、この例の5グループに固定しないでください。
- 個別機能フロー: エントリ、アクション、処理、状態、出口を展開し、分岐条件を注釈します。
- ノード説明と証拠: 責務、直接の関連、実装箇所、制約、検証、状態。
- 変更影響インデックス: 一般的な変更が対応するノード、ファイル、チェック。
概要では二次的な関係を省略できますが、完全なモデルやノード説明からはたどり着けるようにします。要件ドキュメントは引き続き要件の判断を担当し、マップは別の要件ベースラインを構築しません。
HTML ビジュアル納品
HTML が必要な場合は、references/visual.md を読みます。具体的な参考が必要な場合は、references/wechat-example.html を参照します。これは実装済みプロジェクトの例であり、汎用的な事実や固定レイアウトテンプレートではありません。
ノードとセマンティックエッジが同じデータを共有するようにします。ビュー座標、ルーティング、テーマは個別に管理し、Markdown と HTML は同じIDを使用します。シンプルなプロジェクトでは、小さなデータ構造を直接維持し、ジェネレータやグラフライブラリを強制的に導入しません。
ユーザーが確認したビジュアル方向性を保持します。デフォルトでは、中央揃え・幅制限、機能概要エントリ、個別機能フローナビゲーション、図の下に説明、ライト/ダークデュアルテーマを採用します。ノード数と分割方法はコンテンツの密度によって決定します。
例の微信固有の用語、サイズしきい値、未検証状態、手動座標を他のプロジェクトにコピーしてはいけません。製品ルートのグループ化が単なる表示構造である場合、明確にマークし、新規ビジネス機能として扱わないでください。
検証と納品
内容と構造:
- ID は一意。エッジの端点が存在する。主要機能にはすべてドリルダウンエントリがある。削除されたノードに未解決の参照がない。
- 包含、データフロー、依存、制約、検証はそれぞれ意味を持ち、実行順序と混同しない。
- ストレージのライフサイクル、例外出口、実装箇所、状態は証拠によってサポートされる。
- 具体的な変更を一度自問する。例えば「レイアウトを変更すると何に影響するか」、マップは関連する状態、コンシューマ、検証にたどり着ける必要がある。
ビジュアル版は、実際にブラウザで開いてチェックする必要があります:
- 概要はすべての主要機能を同時に表示し、テキストは明確で、矢印はノードやテキストを横切らない。
- 各機能フローを個別に開き、ドリルダウン、図間の関連、選択状態、選択解除を検証する。
- ライトモードとダークモードのテキスト、ノード、線、矢印、説明をチェックし、スクリーンショットを取得する。
- ターゲットデスクトップサイズでの概要の完全性をチェックする。狭いウィンドウでも読みやすいフォントサイズを維持し、図内スクロールまたは分割図への変更を許容する。
静的構文・構造チェックはビジュアルチェックの代わりになりません。ブラウザが利用できない場合は、ファイルを納品し、未完了のチェックを明確にします。古いスクリーンショットを現在の結果として偽装してはいけません。
納品リンク、主要な関係の変更、実際のチェック結果、残りのギャップを提供します。プロジェクトの Git 規約に従って作業を保存します。自分自身でウェブサイトを公開したり、グローバルスキルをインストールしたりしません。