クラフツマン・コーダー: SOLID、AST CodeGraph影響、& エビデンスファースト工学
堅牢で疎結合かつ検証可能なソフトウェアを構築するための、リポジトリに依存しない規律ある工学的ワークフロー。
核となる信条
- AST & CodeGraph探索ファースト: コードを盲目的に変更またはリファクタリングしない。実装を変更する前に、シンボル定義、呼び出し元、呼び出し先、そしてブラストラディウスを常にマッピングする。
- SOLID & 単一責任の原則 (SRP):
すべてのモジュール、関数、クラスは、変更される単一の理由を持つ。ビジネスロジックをI/O、永続化、外部APIから分離する。
- 分解ルール: 1つのコンポーネント、クラス、または関数が長すぎるか、複数の関心事を扱う場合、すぐに単一責任を持つより小さなアトミックなサブコンポーネント/サービスに分解する。
- 依存性注入 (DI) & 制御の反転: 依存関係（リポジトリ、クライアント、ロガー）をコンストラクタまたはフレームワークのメカニズムを介して注入する。ロジックを具体的なインフラストラクチャから切り離す。ハードコードされた直接的な外部インスタンス化を避ける。
- フォールバックアーキテクチャ: 垂直スライスアーキテクチャ (VSA) + EIP:
リポジトリに確立されたフレームワーク規約が存在しない場合、常に垂直スライスアーキテクチャ (VSA) をSOLIDおよびエンタープライズ統合パターン (EIP) と組み合わせて優先する:
- 水平な技術レイヤーではなく、Request-Endpoint-Response (REPR) パターンを使用して、ビジネス機能 (
features/<feature_name>/) ごとにコードを整理する。 - スライス連携にはEIPパターンを採用する: コマンド/クエリルーター、パイプアンドフィルター、べき等レシーバー、ドメインイベントPub/Sub。
- 詳細ガイド: Vertical Slice & EIP ガイド
- 水平な技術レイヤーではなく、Request-Endpoint-Response (REPR) パターンを使用して、ビジネス機能 (
- 確定的 VSA アーキテクチャ境界リンティング:
リポジトリがVSAを実装している場合、スライス間の直接インポートを禁止する確定的な境界リンター（例: JS/TS用
dependency-cruiser、Python用import-linter、Go用depguard、またはvsa_boundary_checker.py）を設定する。- 詳細ガイド: VSA境界強制 & リポジトリGEMINI.mdガイド
- 必須のリポジトリレベル
GEMINI.md(移植可能 & Git対応): リポジトリを作成または初期化する際、アーキテクチャの選択、境界ルール、Gauntletコマンドを永続化するために、常にリポジトリルートにプロジェクトレベルのGEMINI.mdを生成する。- 厳格な移植性ルール: このファイルはコミットされプッシュされるため、外部ホストパス（
~/.gemini/config/...、/data/data/...など）やマシン固有のシークレットを決して参照しない。100%自己完結型で移植可能でなければならない。
- 厳格な移植性ルール: このファイルはコミットされプッシュされるため、外部ホストパス（
- リアルタイムWeb調査 & 最適なBig-O計算量:
最も最適なBig-O時間および空間計算量（$O(1)$ルックアップ、$O(N \log N)$ソート、ストリーミング$O(1)$メモリ）を持つアルゴリズムおよびデータ構造パターンを常に選択する。
- 必須Web調査: 知識が古くなっている可能性があるため、事前学習済みの仮定だけに頼らない。現在の月と年に基づいて常にWebを調査し、最先端のアルゴリズムパターン、最適なデータ構造、最新の高性能ライブラリ実装を発見する。
- 高性能、低RAMライブラリ & エンタープライズライセンス準拠:
- ピークパフォーマンス & 低メモリ: モダンでキャッシュフレンドリー、ゼロコピー、SIMDアクセラレーションされたライブラリ（例:
orjson/msgspec、polars、sonic、zerolog、simd-json、fast-json-stringify）を優先する。 - エンタープライズライセンス準拠: 寛容なオープンソースライセンス（MIT、Apache 2.0、BSD-2/3、ISC）を選択する。ソース開示義務なしにエンタープライズ監査をシームレスに通過させるために、ウィルス性のコピーレフトライセンス（
GPL、AGPL、SSPL）を厳密に避ける。 - 詳細ガイド: 高性能ライブラリ & ライセンスガイド
- ピークパフォーマンス & 低メモリ: モダンでキャッシュフレンドリー、ゼロコピー、SIMDアクセラレーションされたライブラリ（例:
- SRPと抽象化のための確定的静的コード分析: 常に確定的な静的解析ツールを優先してコードを監査し、SRP違反（例: 肥大化した長さ、過剰な責任）や抽象化バイパス（例: プレゼンテーション層やビジネスロジック内での直接の生SQLやHTTP呼び出し）を検出する。
- 集中シークレットインジェクション (Infisical):
シークレットをハードコードしたり、生の認証情報をgit/ローカルenvファイルに保存したりしない。シークレットはInfisical（
infisical run -- ...）を介してランタイム注入される依存関係として扱う。- 詳細ガイド: Infisicalシークレット管理ガイド
- フレームワーク規約ファースト:
アドホックな抽象化を発明するのではなく、既存フレームワークの慣用的な規約（例: FastAPIの
Depends、NestJSの@Injectable、Reactフック、Goインターフェース）を尊重する。 - 並列化可能でハーメティックなテスト:
すべてのテストはステートレスで、隔離され、並列実行可能でなければならない（例:
pytest -n auto、go test -parallel）。共有可能な可変状態や静的なシングルトンの副作用を一切持たない。 - 「Old Coder」のエビデンスファースト規律: コードではなくエビデンスをレビューする。Spec -> RED -> GREEN -> REFACTOR のループに従い、完了を報告する前に自動化されたターミナルチェックを通じて検証する。
- AIエージェント対応ツール & スキル工学:
繰り返し現れるパターンをツールやスキルに抽出する際:
--json出力、非対話型実行（ゼロプロンプト）、--dry-run安全性、予測可能な名詞-動詞の命名、型指定された終了コードを保証する。- 詳細ガイド: AIエージェント対応CLI設計ガイド
ステップバイステップワークフロー
ステップ 1: 変更前のブラストラディウス分析 (CodeGraph AST)
関数、クラス、またはサービスを変更する前に、ブラストラディウスを検査してダウンストリームへの影響を判断する:
python3 ~/.gemini/config/skills/craftsman-coder/scripts/codegraph_impact.py <path_to_repo> --symbol <TargetSymbol>
- 直接呼び出し元と参照ファイルをレビューする。
- 影響を受けるテストスイートをレビューする: このシンボルをテストがカバーしていない場合、リファクタリング前にテストを作成しなければならない。
ステップ 2: アーキテクチャ、アルゴリズムBig-O、リポジトリレベルのGEMINI.md
- 明確な仕様と設計を策定する:
- リポジトリを作成/初期化する場合、自己完結型の
GEMINI.mdをリポジトリルートに作成する（ゼロ外部パス、ゼロシークレット）。 - フレームワーク規約が存在しない場合、垂直スライス（
features/<name>/）をREPRおよびEIPパターンで構成する。 - アーキテクチャ境界リンターをセットアップまたは検証する（例:
dependency-cruiser、import-linter、vsa_boundary_checker.py）。 - クラス/関数/コンポーネントが複数のことを行っていないか、または長さのしきい値を超えていないか？ 焦点を絞ったサブコンポーネントに分解する（SRP）。
- 外部システムが密結合になっていないか？ インターフェース/プロトコルを定義し、依存性注入を使用する。
- アルゴリズム計算量 & Web検索: Big-Oの時間/空間計算量をベンチマークする。現在の月と年に基づいて、最新のアルゴリズム最適化を積極的にWeb検索する。
- 依存関係監査: 低RAM、高スループットでエンタープライズセーフなライセンス（MIT / Apache 2.0 / BSD）のライブラリを選択する。コピーレフト/AGPLの推移的依存関係がゼロであることを確認する。
- リポジトリを作成/初期化する場合、自己完結型の
- 詳細リファレンス: SOLID & DI パターンガイド
- 詳細リファレンス: Vertical Slice & EIP ガイド
- 詳細リファレンス: VSA境界強制 & リポジトリGEMINI.mdガイド
- 詳細リファレンス: 高性能ライブラリ & ライセンスガイド
ステップ 3: 並列化可能なテストを書く (RED)
- 期待される動作やバグ修正を検証する、隔離されたハーメティックなユニットテストまたは統合テストを書く。
- テストが独立した一時リソースまたはインメモリモックを使用していることを確認する。
- テストを実行して失敗することを確認する (RED)。
- 詳細リファレンス: 並列テスト & Old Coderガイド
ステップ 4: 最小限でクリーンなソリューションを実装する (GREEN)
- テストを満たすために必要なものだけを実装する。
- コンポーネントを凝集性が高く、単一目的に保つ。
- 依存関係をクリーンに注入する。
ステップ 5: リファクタリング & Gauntlet (REFACTOR & EVIDENCE)
- テストがグリーンのまま、コードをクリーンアップする。
- Gauntletを実行する（すべての検証は自動化かつ確定的でなければならない）:
- VSA境界チェック:
アーキテクチャ境界チェックを実行する（例:
npx depcruise --config .dependency-cruiser.js srcまたはpython3 ~/.gemini/config/skills/craftsman-coder/scripts/vsa_boundary_checker.py <path_to_repo>）。 - 確定的静的SRP & 抽象化分析:
python3 ~/.gemini/config/skills/craftsman-coder/scripts/static_srp_analyzer.py <path_to_repo> --strict - リンター & 静的解析（例:
ruff check .、eslint、golangci-lint） - 型チェック（例:
mypy、tsc --noEmit） - 完全テストスイートを並列実行する（例:
pytest -n auto、go test -parallel 4 ./...）
- VSA境界チェック:
アーキテクチャ境界チェックを実行する（例:
- 最終的な応答には、ターミナルからのエビデンス（終了コード、テスト合格サマリー）を含める。
組み込みスクリプト & ツール
-
CodeGraph AST 影響分析ツール:
scripts/codegraph_impact.py- Python、JS/TS、Go、Rust、JavaにわたるASTと相互参照を検査する。
- ブラストラディウスのリスクレベル（低、中、高、重大）を計算する。
- 直接呼び出し元と影響を受けるテストスイートを特定する。
-
確定的静的SRP & 抽象化分析ツール:
scripts/static_srp_analyzer.py- SRPの長さ/複雑さの違反についてコードを評価する。
- 抽象化バイパス（リポジトリ/アダプター外での生SQL/HTTP呼び出し）にフラグを立てる。
- CI/Old Coder検証のために、機械可読な
--jsonと確定的な終了コードを出力する。
-
VSA アーキテクチャ境界チェッカー:
scripts/vsa_boundary_checker.py- 不正なスライス間インポートを防止することで、スライスの分離を強制する。
.vsa-boundaries.jsonで設定可能。ゼロ依存、リポジトリ非依存（MIT）。