mcp-examples AGENTS.md

graphify

This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.

When the user types /graphify, use the installed graphify skill or instructions before doing anything else.

Rules:

• For codebase questions, first run graphify query "<question>" when graphify-out/graph.json exists. Use graphify path "<A>" "<B>" for relationships and graphify explain "<concept>" for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
• Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it.
• If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
• Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
• After modifying code, run graphify update . to keep the graph current (AST-only, no API cost).

Documentation Comments

• 実装コードを追加・変更するときは、外部モジュールから利用される public / exported な class, function, type, interface に JSDoc/TSDoc コメントを書く。コメントでは、責務、主要な入力、返却値、失敗条件、副作用、重要な契約が分かるようにする。
• public method では、型だけでは意味・制約・副作用が分かりにくい場合に @param, @returns, @throws を付ける。単に型情報や実装を言い換えるだけのタグは追加しない。
• 非同期 API では、throw される例外だけでなく、Promise rejection、Result 型、error event など、呼び出し側が扱うべき失敗経路を明記する。
• protocol / transport の境界、lifecycle / shutdown、pending request / concurrency、manual input / approval flow、error isolation / recovery など、意図が読み取りにくい private helper には短い意図コメントを書く。
• コメントでは、実装手順をそのまま言い換えるのではなく、目的、契約、前提条件、非自明な tradeoff、呼び出し順序、失敗時の扱いを説明する。
• コードの契約、失敗条件、副作用、呼び出し順序を変更した場合は、対応する documentation comment も必ず更新する。
• テストファイルでは、原則として説明的な test name で仕様を表現する。コメントは、非自明な setup、race condition、timing behavior、微妙な protocol expectation がある場合だけ短く追加する。
• この repository では documentation comment を日本語で書く。ただし、protocol 名、error code、外部仕様・API に由来する用語、識別子は原語のまま扱ってよい。