Swift-Selena: Instructions file for Claude Code

CLAUDE.md

Swift-Selena = MCP Server for Swift code analysis (Swift Package)

AI Interaction Language [MANDATORY]

すべての対話は日本語で実施すること

• 技術用語・英単語はそのまま使用可能
• ソースコードのコメントも日本語で記述
• ファイル記述も日本語。ただし修正前のファイルがすでに英語記述の場合は、そのまま英語記述

Important Constraints [MANDATORY]

• NEVER modify Xcode project files (*.xcodeproj/) without explicit permission
  • 注: フォルダーベース登録済みのため、ファイル追加時は変更不要
• NEVER modify Info.plist or XCConfig files without explicit permission
• 要件定義書（specs/{feature}/requirements/）が最優先（すべてのドキュメントに優先）
• 文書不整合の即時報告: rules/、specs/、.claude/ 内の文書で不整合・矛盾を発見した場合、作業を中断して最優先でユーザーに報告すること
• Use existing code before creating new ones (Tools/, Library/)
• 既存コード参考必須: 新規コード作成前に、既存の類似実装を検索して参考にすること
• ファイルヘッダーのCreated by: git config user.nameの値を使用
• 作業開始時の文書検索: 文書読解が必要な作業は、/forge:query-db-rules /forge:query-db-specs で関連文書を特定し、該当する文書を読んでから作業に入ること
• DB インデックス自動更新: rules/ 配下の文書を追加・変更・削除したら /forge:update-db-rules、specs/{feature}/requirements/ または specs/{feature}/design/ 配下の文書を追加・変更・削除したら /forge:update-db-specs を実行すること
• DB インデックス直接編集禁止: .claude/doc-advisor/ および .claude/doc-db/ 配下のインデックスファイルは直接編集せず、/forge:update-db-rules / /forge:update-db-specs で更新すること
• Swift-Selena MCP の利用検討: Swift-Selena MCP が接続されている場合、コードの分析・解析作業で MCP の説明から効率的・効果的か判定し、利用を検討すること（実験は不要、MCP の説明で判断）
• Xcode MCP の利用検討: Xcode MCP が接続されている場合、Skill（/xcode:build / /xcode:test）が対応していない場面でのみ、MCP の説明から効果的か判定し、利用を検討すること
• MCP サーバー再起動を伴うテストはユーザー依頼必須: MCP サーバー（Swift-Selena MCP 等）の再起動を要するエンドツーエンドテスト（コード変更後の挙動確認、キャッシュ破棄を伴う動作確認など）は、AI が独断で実施せず、必ずユーザーに再起動を依頼してから実施すること
  • AI 側からは別プロセスである MCP サーバーを再起動できない
  • 再起動が必要な場合は、再起動手順（バイナリ再ビルド要否、必要なキャッシュ削除、確認したい挙動）を明示してユーザーに依頼する
  • ユニットテストでの代替検証で済む場合はそれを優先し、E2E 検証の要否を判断する
• バージョン表記規約（Issue #38 で確立。プロジェクト全体で参照すべき正規）:
  • canonical（真実の源）: Sources/Constants.swift の AppConstants.version（例: "0.6.10"）。/forge:update-version で更新する
  • git tag: MAJOR.MINOR.PATCH 形式（v プレフィックスなし、例: 0.6.10）。既存 16 個の tag と整合
  • CHANGELOG.md header (新規 entry): ## VERSION - YYYY-MM-DD 形式（v プレフィックスなし、例: ## 0.6.10 - 2026-05-27）。過去 entry (## v0.6.X 形式) は historical record として遡及修正しない
  • .version-config.yaml の tag_format は "{version}"（v なし）
  • 例外: README.md / README.ja.md 内の「機能 X は v0.6.3 以降で利用可能」等の機能登場版マーカーは v 付きを許容（独立した文脈表記）
  • 検証: scripts/verify_version_consistency.sh で canonical（Sources/Constants.swift）・CHANGELOG 先頭 entry・.version-config.yaml の tag_format / version_file / version_path の一致を確認。CI ワークフロー .github/workflows/version_check.yml で PR ごとに自動検証
  • Formula は verify script 対象外: Formula/swift-selena.rb の tag: / revision: は git object 識別子（revision = tag が指す commit の SHA）に従属し、rebase / squash で SHA が変わり得るため、version 文字列の静的一致を検査する verify script の必須チェックには含めない。Formula の整合性は後述の release フロー（tag 確定後の git rev-parse {version}^{commit} と Formula revision の一致確認）と brew install 実検証で担保する
• リリースタグは main 履歴上の「version bump commit」に作成する: {version} 形式（v プレフィックスなし）のリリースタグは、必ず main にマージ済みの version bump commit（後述 ①） に対して作成すること
  • develop 等の作業ブランチで先行して git tag を打たない（main にマージし、main へ checkout してから打つ）
  • tag は merge commit ではなく ① の commit に打つ。これにより revision（= ① の SHA）を merge 前に確定でき、Formula を version bump と同一 PR に同梱できる
  • タグ作成前に git branch --show-current で main に居ること、git merge-base --is-ancestor <①のSHA> main で ① が main 履歴に含まれることを確認する
  • 誤った commit / ブランチで作成したタグは git tag -d <tag> && git push <remote> :<tag> で削除し、正しい commit で切り直す
• release の運用順序（Formula 同梱・単一マージ）: tag を version bump commit（①）に打つことで revision を merge 前に確定できるため、Formula 更新を version bump と同一 PR に同梱し、main へのマージを 1 回に集約する。以下の 2 フェーズで実施する
  • Phase 1 — bump PR（作業ブランチ）:
    1. /forge:update-version <target> <patch|minor|major> を実行（Sources/Constants.swift 更新 + CHANGELOG への新規 entry 挿入）し、commit ①（Constants + CHANGELOG のみ）として commit
    2. git rev-parse HEAD で ① の SHA を取得
    3. Formula/swift-selena.rb の tag: を {version}、revision: を ① の SHA に更新し、commit ②（Formula のみ）として commit
    4. scripts/verify_version_consistency.sh（version 文字列の一致）+ brew style Formula/swift-selena.rb（Formula 文法）でローカル検証
    5. push し、PR を作成・マージ（develop 等の作業ブランチ）
  • Phase 2 — main マージ + tag（main 上）: 6. develop の変更を main に --no-ff マージ（① の SHA を保存するため。squash / rebase マージは不可）→ push 7. main に checkout し git branch --show-current で確認 → git tag {version} <①のSHA> → git push <remote> {version} 8. scripts/verify_release_tag.sh {version} で「tag が指す commit == Formula の revision（① の SHA）」かつ「Formula tag: == {version}」を検証（不一致なら exit 1）。CI release_tag_check.yml でも tag push 時に main の Formula に対し自動検証される 9. tap 反映後、brew install --build-from-source で実 install 検証（serverInfo.version == {version}）
• 既存 release artifact の drift について（documented limitation）: 本規約は HEAD 以降で commit される変更にのみ適用される。既存 release tag（例: 0.6.10）のソース内 AppConstants.version 等が drift していても、本規約では遡及修正しない（git 履歴の整合性保持）。Homebrew で install される既存 release バイナリの serverInfo.version が canonical と一致しない場合、それは「既知の historical drift」として受容し、次回 release で初めて完全整合する