core-principles

コア原則

これは厳格なガイドラインです。 以下のルールに従ってください。他のスキルが以下のルールと矛盾する場合は、このスキルが優先されます。

すべてのプロジェクトに適用される基本ガイドラインです。

重要：これらは指針となる原則であり、絶対的なルールではありません。プロジェクトの状況も重要です。逸脱する必要がある場合は、その理由とトレードオフを説明してください。

例に関する注記：コード例では、分かりやすさのために特定の言語（JavaScript、Python など）を使うことがありますが、原則はすべての言語に適用されます。プロジェクトの言語や状況に合わせてパターンを調整してください。

---

1. 純粋関数を優先する

ヘルパー関数は、グローバル変数や環境変数を読み取るのではなく、データをパラメーターとして受け取るようにしてください。

// ✅ Preferred: Pure, testable, moveable
function buildResourceName(environment: string, type: string, name: string): string {
  return `${environment}-${type}-${name}`;
}

// ⚠️ Less ideal: Reads from global
const ENV = process.env.ENVIRONMENT;
function buildResourceName(type: string, name: string): string {
  return `${ENV}-${type}-${name}`;
}

不純な処理が必要な場合（AWS の呼び出し、DB アクセス）：スコープを最小限に抑え、可能であればクライアントをパラメーターとして渡してください。

2. 暗黙のデフォルト値を使わない — 速やかに、明確に失敗させる

フォールバック値はほとんど使わないでください。設定の不足、データフィールドの不足、想定外の状態があれば、意味のあるエラーメッセージを表示して、ただちに明確に失敗させてください。

// ❌ Silent fallback — masks misconfiguration
const region = process.env.AWS_REGION || 'us-east-1';

// ✅ Fail fast with actionable error
if (!process.env.AWS_REGION) {
  throw new Error('AWS_REGION is required. Set in environment or SSM.');
}
const region = process.env.AWS_REGION;

# ❌ Silent default — hides corrupt data
source = status.get("scrape_source", "")

# ✅ Required field — let it fail if missing
source = status["scrape_source"]

唯一の例外 — ユーザー向けの回復性：1件の不正なレコードや必須ではないフィールドの不足によって、API エンドポイントやフロントエンドコード全体がクラッシュしてはいけません。この場合は、次のようにしてください。

• エラーをループ／項目単位で捕捉する（フィールド単位ではなく）
• 識別に役立つコンテキスト（pk、sk など）とともに、エラーの全体をログに記録する
• 不正なレコードをスキップし、残りを提供する
• すべてのフィールドに .get("field", "") のようなデフォルト値を散在させない — データの不具合が暗黙に隠れてしまいます

# ✅ Correct: required fields fail loud, but one bad record doesn't crash the endpoint
for item in items:
    try:
        result.append(format_item(item))  # format_item uses item["field"] — no defaults
    except (KeyError, ValueError):
        logging.exception("Skipping corrupt item: pk=%s sk=%s", item.get("pk"), item.get("sk"))

何かが「必須ではない」かどうか判断に迷う場合は、作業を止めて相談してください。基本方針は明確に失敗させることです。

3. コードの構造と整理

一貫したファイル構成と、関心事の明確な分離を目指してください。

推奨するファイル構成：

1. インポート
2. 環境変数の検証（コールドスタート時に速やかに失敗させる）
3. 定数
4. AWS クライアントとコストの高い初期化処理
5. 型／インターフェース
6. 純粋なヘルパー関数
7. 不純な関数（AWS の呼び出し、I/O）
8. エントリーポイント（ハンドラー、main など）

関心事の分離：

• スキーマ、プロンプト、ビジネスロジックには、別々のファイルを使うことを優先してください
• 無関係な機能を混在させないでください
• 分離と過度な細分化のバランスを取ってください

関数の宣言：

• シンプルな処理／インライン処理：アロー関数 const fn = () => {}
• 複雑なロジック：function キーワード function fn() {}

4. 設定内のプロジェクト識別子

プロジェクト識別子をハードコーディングしないでください。代わりに設定を使ってください。

// ❌ Avoid
const paramPath = `/myapp/${environment}/api-key`;

// ✅ Preferred
const PROJECT_ID = process.env.PROJECT_ID;
const paramPath = `/${PROJECT_ID}/${environment}/api-key`;

5. エラー処理

基本方針は、速やかに明確に失敗させることです。適切な縮退運転はまれな例外であり、通常の対応ではありません。

• 例外を送出する／クラッシュさせる：設定の不足、必須データフィールドの不足、無効なセットアップ、重要な依存関係。これが基本です。
• ログに記録して項目をスキップする：不正な項目によって応答全体が失敗してはならない、ユーザー向けの境界（API 応答、フロントエンドのレンダリング）でのみ行います。項目単位で捕捉し、コンテキストとともにログに記録して、その項目をスキップしてください。
• 決して行わないこと：エラーを回避するために、暗黙のデフォルト値（.get("field", "")）を散在させないでください。これでは不具合が隠れてしまいます。
• 必ず行うこと：エラーには、どのレコード、どのフィールド、何が期待されていたかなど、対応に役立つコンテキストを含めてください。

6. 変数の命名

意味が明確な変数名を使ってください。広く定着した慣例を除き、1文字の名前は避けてください。

// ❌ Avoid
arr.map((a) => a.id);
catch (e) { console.error(e); }

// ✅ Preferred
users.map((user) => user.id);
catch (err) { console.error(err); }

許容される略語：err、evt、req、res、ctx、idx、fn

例外：数式（x、y、i、j）、単純なアロー関数（[1,2,3].map(n => n * 2)）

7. セキュリティの基本方針

• シークレット、API キー、認証情報をリポジトリに含めないでください
• AWS Secrets Manager または SSM Parameter Store（SecureString）を使用してください
• シークレットはビルド時ではなく、実行時に取得してください
• ハードコードされた認証情報より IAM ロールを優先してください
• 環境ごとにリソースとシークレットを分けてください

---

段階的な改善

このスキルで防げたはずの動作を開発者が修正した場合は、同じ修正が今後発生しないよう、このスキルに加える具体的な改訂を提案してください。