code-general

name	code-general
description	言語固有の実装スキルが適用できない、または言語をまたぐ既存コードベースの機能追加、修正、リファクタリングで守る共通原則と進め方を定義する。仕様や公開契約を壊さず、既存構造、命名、責務境界に合わせて小さく安全な差分を作るときに使う。Go 実装では code-go など該当する言語別スキルを併用し、レビューのみは code-review を優先する。

Code General

目的

言語やフレームワークに依存しない実装作業の共通原則を、小さく、安全で、意図が明確な差分に落とし込む。 動くだけでなく、既存コードベースの読まれ方、直され方、テストされ方に自然に馴染ませる。

言語固有の判断が必要な場合は、このスキルだけで判断せず、該当する言語別スキルを併用する。 Go 実装では code-go を併用する。TypeScript、React、Ruby、CSS などでも対応する言語別スキルがある場合はそれを優先して参照する。

優先順位

判断に迷ったら、原則として次の順で優先する。

1. 既存の仕様、公開契約、データ互換性を壊さない。
2. 既存コードの構造、命名、責務分割、エラー処理に合わせる。
3. 変更を必要最小限に保つ。
4. 将来の保守性、テスト容易性、調査容易性を損なわない。

最小変更が責務混在やテスト不能な構造を固定化する場合だけ、変更範囲を説明できる小さな構造改善を含める。 大きな設計変更が必要な場合は、実装に入る前に方針を分けて整理する。

実装前に確認すること

コードを書く前に、最低限次を確認する。

• 何を変えるか、何を変えないか。
• 既存コードで同じ責務を担う場所はどこか。
• 入力、出力、エラー、永続化、外部 I/O の契約は何か。
• 正常系、異常系、境界条件を何で検証するか。
• プロジェクト固有の規約、生成物、フォーマッタ、テストコマンドは何か。
• これから実装する言語やフレームワークに対応する skill を必要に応じて併用する。
  • Go 実装や Go テストでは code-go を使う。
  • TypeScript 実装では code-ts を使う。
  • React 実装では code-react を使い、TypeScript の型設計も必要な場合は code-ts も併用する。
  • Ruby / Rails 実装や Ruby / Rails テストでは code-ruby を使う。
  • CSS 実装では code-css を使う。

不明点は既存実装、既存テスト、既存命名から先に確認する。 それでも決まらない場合は、仮定を明示して最小の判断にとどめる。

実装時の判断原則

• 1つの差分に複数の意図を混ぜない。
• ドメイン判断、状態管理、I/O、表示、永続化の責務を混ぜない。
• コントラクト層の型、API、エラー表現を厳密にし、実装詳細を漏らさない。
• 関数は単一の意図で説明できる大きさに保つ。
• 条件分岐が増える場合は、責務ごとの型、関数、インターフェースに押し戻せないか確認する。
• 名前だけで役割が分かるようにする。
• コメントは「なぜ」を補う場合だけ書く。
• 生成物や vendored code は、プロジェクトの手順がある場合だけ編集する。

命名に迷った場合

関数名、メソッド名、クラス名、型名、変数名、ファイル名などの命名判断で迷う場合は、code-naming を併用する。

特に次の場合は code-naming の基準を参照する。

• 既存名が曖昧、汎用的、または責務に対して広すぎる。
• 新しい概念を追加し、既存コードの語彙と揃える必要がある。
• Boolean、変換関数、副作用のある関数、インターフェース名の読みやすさを判断したい。
• 複数の候補から、検索性と呼び出し側の自然さを基準に選びたい。

実装の進め方

1. 関連コードとテストを読み、既存の流儀、責務境界、命名規則を把握する。
2. 変更範囲を絞り、今回やることとやらないことを決める。
3. 必要なら先にテスト観点や検証方法を決める。
4. 既存パターンに沿って最小の差分で実装する。
5. フォーマット、静的検査、テストを実行する。
6. 差分を見直し、不要変更、責務混在、命名の違和感、検証漏れを取り除く。

完了前チェックリスト

• 変更意図が差分から読める。
• スコープ外の変更を持ち込んでいない。
• 既存の命名、構造、責務分割に揃っている。
• 重要な正常系、異常系、境界条件を検証している。
• テストまたは他の検証手段で変更の妥当性を説明できる。

出力

最終報告は次を簡潔に含める。

1. 変更した内容
2. 変更ファイルと主要な行
3. 実行した検証
4. 未実行の検証や残るリスク
5. 使用した skill