mcp-jp-corporate-id: Instructions file for Claude Code

CLAUDE.md

このファイルは、このリポジトリで作業するすべてのAIアシスタント(Claude Code等)に対する プロジェクト固有の指示です。

1. 法令・制度データは必ず一次情報を実際に開いて照合すること

• 検査用数字(チェックデジット)の算式、法人番号・会社法人等番号の構成、法人種別コード、 インボイス登録番号の体系など、番号の検証ロジックに関わる数値・算式・仕様は、 記憶やそれらしい一般知識で書いてはならない。
• 必ず国税庁法人番号公表サイト(https://www.houjin-bangou.nta.go.jp/)、 国税庁インボイス制度適格請求書発行事業者公表サイト(https://www.invoice-kohyo.nta.go.jp/)、 e-Gov法令検索(https://laws.e-gov.go.jp/)などの一次資料を実際に取得し、内容を 突き合わせてから実装すること。PDF等バイナリはWebFetchで内容が取得できないことが あるため、その場合はブラウザで開くかファイルとして保存して読むこと。
• 二次資料(会計事務所・司法書士事務所のブログ、HR/経理系メディアの解説記事等)は、 一次資料が見つからない場合の手がかりとしてのみ使い、最終的な根拠にはしない。 複数の二次資料が食い違う場合(例: 会社法人等番号の組織区分コード)は、それ自体が 「一次資料での確認が必要」というシグナルとして扱うこと。
• 一次資料のURLは、src/sources.ts とREADME(日英)の出典一覧に、実際に照合した 日付とともに記載すること。

2. 照合できなかったものは「未検証」と明示的に申告すること

• 一次資料で確認できなかった数値・コード表・仕様は、確認できたかのように書かない。
• 実際にあった例: 会社法人等番号の「組織区分(2桁)」と法人種別(株式会社等)の対応表は、 商業登記規則第1条の2の条文を確認しても数字コードとしては明記されておらず、 二次資料でも情報源によって内容が食い違っていた。このため parse_corporate_number は組織区分の生の数字のみを返し、法人種別のラベル付けは行わないという設計にしている。 安易に確からしい二次資料の値を採用しないこと。
• README・コード内コメントに、未検証事項を隠さず記載すること (README.ja.md の「未検証・確認できなかった事項」を参照)。

3. 修正作業のあとは、別の箇所を壊していないか必ず確認すること

• ある関数・データ構造の設計を変更したら、それを参照している他の箇所 (別のツールの出力、コメント、README、テストのモックデータ等)が古い前提のまま 残っていないか、変更後に横断的に検索して確認すること (例: grep -rn "<削除したフィールド名>" src tests README.ja.md README.md)。
• 修正後は必ず npm run build && npm test を実行し、全テストが通ることを確認する。 既存のテストが新しい設計と合わなくなった場合は、テストを削除するのではなく、 新しい設計を正しく検証する内容に書き換えること。

4. 引数設計では、判断や分類をツール側が引き受けること

• 呼び出し側(AIやユーザー)に、法的な分類判断(「この日数は分子に入れるべきか」 「この理由は除外事由に当たるか」等)をさせてはならない。分類こそがツールの 提供すべき価値であり、同時に誤りが混入しやすい部分である。
• 引数は、呼び出し側が客観的に数えられる生の事実(日数・日付など)を渡す形にし、 それをどう扱うかの判断(法的な分類・計算)はツール内部のロジックが担うこと。
• 引数名・説明文は、AIが読んで一意に解釈できる粒度で書くこと。
• 分類や計算の根拠になった条文・一次資料は、応答に含めること(呼び出し側が 検証・監査できるようにするため。sources フィールド)。
• 不明な値がある場合は、0やデフォルト値を推測して補わず、エラーを返すこと (例: calculate_check_digit・parse_corporate_number は桁数が合わない入力に 対してパディング等を行わずValidationErrorを投げる)。
• ただし「validate_*」系のツール(妥当かどうかを判定すること自体が目的のツール)は、 形式が不正な入力自体を例外にせず、valid: false / formatValid: false として 結果に含めること。不正な形式であること自体が有効な判定結果だから。