software-craft

ソフトウェアエンジニアリング

エンジニアリング判断 - 思慮深い意思決定 - 高品質なコード。

<when_to_use>

• アーキテクチャや設計の意思決定を行うとき
• アプローチ間のトレードオフを評価するとき
• 適切な徹底度を判断するとき
• コードのリファクタリングが必要なタイミングを評価するとき
• 質問すべきか、独立して進めるべきかを判断するとき
• 速度、品質、保守性のバランスを取るとき

対象外: 機械的なタスク、明確な判断、明示的な指示への従順

</when_to_use>

エンジニアリング判断の中核となるフレームワーク。

ユーザーの好みはデフォルトに優先する CLAUDE.md、プロジェクトのルール、既存のパターンは常にスキルの提案を上書きします。

動作する最もシンプルなもの シンプルに始めましょう。複雑さは要件が求めたときにのみ追加します。

• 退屈な問題には退屈な解決策を
• カスタム実装よりも実績のあるライブラリを
• 書き直しよりも段階的な強化を

書く前に読む 変更する前に既存のパターンを理解しましょう。

• 類似の機能がどのように実装されているかを確認する
• 確立された規約に従う
• 一貫性を維持する

小さく焦点を絞った変更 1 コミットにつき 1 つのアイデア、20〜100 LOC、1〜5 ファイル。

• レビューしやすく理解しやすい
• バグのリスクが低い
• 元に戻すのが簡単
• フィードバックが速い

セキュリティへの意識 脆弱性を持ち込まないこと。

• 外部入力を検証する
• パラメータ化クエリ
• 認証を適切に処理する
• コードやログにシークレットを残さない

止めるべきときを知る 動作するコードを出荷し、過剰に磨き上げないこと。

• 仮定ではなく要件を実装する
• 要求されていない機能は入れない
• 投機的な抽象化はしない

<type_safety>

言語を問わない型安全性。

中核原則: 不正な状態を表現不可能にすること。型システムは実行時ではなくコンパイル時に無効なデータを防ぐべきです。

階層: 正しい (型安全) - 明確 (自己文書化) - 正確 (過度に広範でない)

主要なパターン:

• Result 型 - エラーを例外に隠さず、シグネチャで明示する
• 判別可能なユニオン - 判別フィールドを持つ相互排他的な状態
• ブランド型 - ドメイン概念に対する区別された型 (ユーザー ID と製品 ID)
• 検証せずパースする - 境界で型なしを型付きに変換し、内部では型を信頼する

詳細な概念については type-patterns.md を参照してください。 TypeScript の実装については typescript-dev/SKILL.md を読み込んでください。

</type_safety>

<decision_framework>

エンジニアリング上の選択に対する体系的なアプローチ。

決定する前に理解する

• どのような問題を解決しようとしているのか?
• どのような制約があるのか?
• コードベースに既に何があるのか?
• プロジェクトはどのようなパターンを使っているのか?

トレードオフを考慮する 完璧な解決策はありません:

• 速度と堅牢性
• シンプルさと柔軟性
• 一貫性と最適化
• 実装時間と保守時間

十分に良いを認識する 完璧は出荷の敵です:

• 要件を満たしているか?
• チームが保守できるか?
• 適切にテストされているか?
• 段階的に改善できるか?

すべてに「はい」なら、それを出荷しましょう。

重要な選択を文書化する 自明でない決定: 理由をコメントし、トレードオフを記し、議論をリンクし、仮定に印を付けます。

</decision_framework>

<when_to_ask>

自律性と協働のバランス。

独立して進める:

• タスクが明確でよく定義されている
• アプローチが既存のパターンに従っている
• 変更が小さく局所的である
• 要件が完全に理解されている
• セキュリティやデータ整合性のリスクがない

質問する:

• 要件が曖昧
• 複数のアプローチがあり、トレードオフが不明確
• 変更がアーキテクチャに影響する
• セキュリティやコンプライアンスへの影響がある
• 分野や技術に不慣れ

すぐにエスカレーションする:

• セキュリティ脆弱性を発見した
• データ破損や損失のリスク
• パブリック API への破壊的変更
• パフォーマンス低下を検出した

重要な決定で推測してはいけません。

</when_to_ask>

<code_quality>

優れたコードとプロフェッショナルなコードを分ける基準。

型安全性: 判別可能なユニオンやブランド型によって、不正な状態を表現不可能にします。

エラー処理: すべてのエラーパスに明示的な処理が必要です。サイレント障害は許されません。

命名: 関数=動詞 (calculateTotal)、変数=名詞 (userId)、真偽値=疑問形 (isValid)。

**関数設計**: ひとつのことをうまくやる。典型的には10〜30行、最大50行。理想は3パラメータ、最大5。可能な場合は純粋関数に。

コメント: 何をするかではなく、なぜそうするかを説明する。

例については code-quality-patterns.md を参照してください。

</code_quality>

既存のコードをいつ、どのように改善するか。

リファクタリングすべきとき:

• 機能追加によって構造のまずさが明らかになった
• コードが3回以上重複している
• 関数が50行を超えている
• 命名が不明確または誤解を招く
• テストが書きにくい

リファクタリングすべきでないとき:

• コードが動作しており、今後触られる予定がない
• 納期が迫ったリリース作業の進行中
• 検証するためのテストカバレッジがない
• 本題からのスコープクリープになる
• 明確な利点がなく、単なる好みである

ガイドライン:

• まずテストを用意する(または書く)
• 一度にひとつのリファクタリングを行う
• その間もテストが通り続けるようにする
• リファクタリングは機能追加とは別にコミットする
• 振る舞いを変えない

テストの考え方。

正しいものをテストする:

• 実装ではなく公開インターフェース
• エッジケースとエラーパス
• 重要なビジネスロジック
• 統合ポイント
• セキュリティ境界

過剰にテストしない:

• 些細な getter/setter のテストは書かない
• フレームワークの振る舞いをテストしない
• 実装に密結合した壊れやすいテストを避ける

カバレッジの目標:

• クリティカルパス: 90%以上
• ビジネスロジック: 80%以上
• ユーティリティ関数: 80%以上
• 全体: 70%以上

低いカバレッジが許容されるもの: 設定、型定義、フレームワークのボイラープレート。

最適化とリリースのバランスを取る。

早すぎる最適化は諸悪の根源

• まず動作させる
• 次に正しくする
• 必要な場合にのみ速くする

最適化すべきとき:

• 測定されたパフォーマンス問題が存在する
• ユーザー体験が損なわれている
• リソースコストが過大である
• プロファイラが明確なボトルネックを示している

最適化の前に:

1. 現在のパフォーマンスを測定する
2. 目標指標を設定する
3. プロファイリングしてボトルネックを見つける
4. 特定のボトルネックを最適化する
5. 改善を測定する
6. トレードオフを文書化する

勘や測定なしに最適化しないでください。

すべてのコードにおけるセキュリティの意識。

入力検証: すべての外部入力を検証し、処理前にサニタイズし、ブロックリストよりも許可リストを使う。

認証: クライアント側のチェックを決して信頼せず、サーバー側で検証し、実績のあるライブラリを使い、独自の暗号を実装しない。

データの取り扱い: 機密データを決してログに記録せず、パスワードをハッシュ化し(bcrypt/argon2)、パラメータ化クエリを使い、ファイルアップロードを厳格に検証する。

依存関係: 最新の状態を保ち、アドバイザリを確認し、数を最小限にし、追加前に監査する。

エスカレーションすべき危険信号: 支払い情報、ユーザー資格情報、健康・金融データ、暗号化の実装、セッション管理。

<anti_patterns>

避けるべきよくある間違い。

過剰設計: 「必要になるかもしれない」機能を作り込む、早すぎる抽象化、過剰な設定、単純な問題へのエンタープライズパターン。 対策: YAGNI。今日のためのものを作る。

設計不足: エラーハンドリングなし、入力検証なし、エッジケースの無視、関数化せずにコピー&ペースト。 対策: 基本品質は任意ではない。

スコープクリープ: 「ついでに…」、無関係なコードのリファクタリング、求められていない機能の追加。 対策: 集中を保つ。無関係な作業は issue として起票する。

当てずっぽう: 場当たり的な解決策、理解せずにコピー、根本原因の調査なし。 対策: 体系的なデバッグ。変更する前に理解する。

分析麻痺: 終わりのない設計議論、あらゆる選択肢の調査、完璧を待つこと。 対策: 十分な品質+リリース > 完璧+遅延。

</anti_patterns>

シニアエンジニアのコラボレーション。

明確な issue/PR: コンテキスト(問題)、アプローチ(解決策)、トレードオフ(代替案)、テスト(検証)、影響(リスク)。

コードレビュー: 正確性・明快さ・セキュリティに焦点を当てる。完璧を要求せず提案する。十分に良ければ承認する。

行き詰まったとき: 30分は自分で解決を試み、コンテキストを集め、コンテキストを添えて具体的な質問をし、解決策を提案する。

断るとき: 「それはうまくいくでしょうが、X を検討しましたか?」/「これは Y というリスクをもたらします。Z で軽減できますか?」 意見には根拠を添えてください。間違っている可能性に対して常にオープンでいてください。

<workflow_integration>

他の outfitter スキルと連携します。

TDD との連携: 何をテストする価値があるかはシニアの判断が決めます。その方法は TDD スキルが提供します。

デバッグとの連携: 今修正する価値があるかはシニアの判断が決めます。体系的な調査はデバッグスキルが提供します。

dev- スキルとの連携*: ソフトウェアエンジニアリングは「なぜ」と「いつ」を提供します。特定の技術（typescript-dev、react-dev、hono-dev、bun-dev）の「どのように」は dev-* スキルが提供します。

</workflow_integration>

常に:

• 最初に CLAUDE.md とプロジェクトのルールを読む
• 既存のコードベースのパターンに従う
• 小さく焦点を絞った変更を行う
• 外部入力を検証する
• エラーを明示的に処理する
• クリティカルパスをテストする
• 自明でない判断を文書化する
• 影響が大きい場合は不確かなときに質問する

決してしない:

• 要件にない機能を追加する
• エラー処理を無視する
• 入力検証を省略する
• シークレットや認証情報をコミットする
• セキュリティ上の判断を推測で行う
• テストなしでリファクタリングする
• 計測なしで最適化する
• シンプルな解決策を過剰に設計する

他の outfitter スキルを補完します:

中核プラクティス:

• tdd/SKILL.md - TDD 方法論
• debugging/SKILL.md - 体系的なデバッグ
• pathfinding/SKILL.md - 要件の明確化

開発スキル (実装パターンのために読み込む):

• typescript-dev/SKILL.md - TypeScript、Zod、モダンな機能
• react-dev/SKILL.md - React 18-19、フックスの型付け
• hono-dev/SKILL.md - Hono API フレームワーク
• bun-dev/SKILL.md - Bun ランタイム、SQLite、テスト

詳細パターン:

• type-patterns.md - 言語に依存しない型パターン
• code-quality-patterns.md - コード例

標準: