i-Willink Dev Standards (stack-agnostic)

このスキルは i-Willink 全プロジェクトに共通する開発標準。スタック特化のルールは含まない — それは各プロジェクトの project-standards skill が担う。

1. コード品質

言語横断

• 意図が読める命名: 短さより明瞭さ。d ではなく dueDateUtc
• コメントは「WHY」が非自明な時のみ: 制約・不変条件・回避策・読み手が驚く挙動。WHAT を書かない（コード自体が説明する）
• 早期 return で nest を浅く: ガード節で例外条件を最初に処理
• YAGNI: 仮想の将来要件のための抽象化禁止。3 行類似は重複ではなく「まだ重複じゃない」

TypeScript（採用プロジェクトのみ適用）

• strict: true 必須。any 禁止、unknown を使い narrowing する
• noUncheckedIndexedAccess: true 推奨
• 型の export は type キーワード明示

Flutter / Dart（採用プロジェクトのみ）

• analysis_options.yaml の strict-casts / strict-inference / strict-raw-types を有効化
• null safety を抜けない（! の使用は局所化して justify コメント）

PHP / WordPress（採用プロジェクトのみ）

• PHPCS WordPress-Extra 準拠
• wp_unslash() / sanitize_*() / esc_*() は 境界で必ず実施

2. テスト方針

• 境界では検証、内部では信頼: 外部入力・API・DB 境界を厚く、純粋関数の internals は薄く
• happy path だけでは不十分: edge case と failure path を必ず 1 本ずつ
• モックは外部境界のみ: 内部関数のモックは設計が壊れているサイン
• テストの命名: test_<対象>_<条件>_<期待結果> 形式（言語慣習に従って adapt）
• 新規コード: カバレッジ 80% 以上目安（hard rule ではない・behavior coverage を優先）

3. アクセシビリティ（UI に触る全変更に適用）

後付け禁止。UI を追加/変更するときに設計事項として決める。後から監査で足すと「操作要素が全部無名」のような構造的欠陥になり、修正が全画面に散る。

最低ライン（これを満たすまで実装完了としない）:

• name / role / state — 操作要素はすべて accessible name を持ち、役割（button 等）と状態（無効/選択/トグル）を公開する（WCAG 2.2 SC 4.1.2）
• 記号をラベルにしない — < × … は記号名で読み上げられる（< は「小なり」）
• 文字拡大 200%（iOS 最大 ≒ 3.12x）でレイアウトが壊れない — 固定高さに文字を詰めない
• コントラスト 本文 4.5:1 / 大きい文字・UI 部品 3:1、ターゲットサイズ 最小 24×24 CSS px（モバイルは 48）
• 主要導線 1 本は読み上げだけで通せる — ここが受入条件。静的ゲートが緑でも、これは人手で確認する

→ スタック別の書き方・検証手段（決定論ゲート / 自動テスト / 実機）は a11y-standards skill。 機械検査は a11y-static-gate（scripts/a11y-static-check.py・exit code で判定）。

4. セキュリティ

OWASP Top 10 を常に意識

• Injection: prepared statements / parameterized queries 必須
• Broken Access Control: 認可は API 層で必ず（フロントだけはダメ）
• Cryptographic Failures: 自前 crypto 禁止、ライブラリ標準を使う
• SSRF / XSS / CSRF: フレームワークの保護機構を無効化しない

秘密情報

• .env をコミットしない（.env.example のみ管理）
• API キー・トークンをコードに hardcode 禁止
• ログに secrets を出さない（マスキング必須）

5. コミット規約

Conventional Commits 必須:

<type>(<scope>): <subject>

[body — WHY を書く]

[footer]

type

• feat: 新機能
• fix: バグ修正
• docs: ドキュメントのみ
• refactor: 振る舞いを変えない構造変更
• test: テストのみ
• chore: ビルド・依存・設定
• perf: パフォーマンス改善
• style: フォーマットのみ

コミット粒度

• 1 commit = 1 論理変更。レビューしやすさ最優先
• 大きな変更は分割（feat 1 件で 800 行超えたら分割を検討）
• WIP commit を main に混ぜない（feature branch 上では OK・squash で消す）

6. PR 運用

• 小さく、レビューしやすく: 500 行超は分割を真剣に検討
• PR description で WHY を語る: WHAT は diff で読める
• Self-review してから request review: 自分で 1 周読む
• CI green で初めて merge 可能

7. AI 開発（Claude Code / Codex 使用時）

• Generator-Verifier 分離: 実装はメイン agent（Claude Code は main Claude、Codex は main Codex）、レビューは Verifier role（dev-reviewer 相当）
• Telephone game 回避: 順序的同一作業を subagent 連鎖に分割しない
• Early victory 警戒: テスト 1-2 本で「成功」を信じない（dev-tester プロトコルに従う）
• 同一ファイル並列編集禁止: subagent 並列起動時は read-only に限定
• Codex subagent は明示許可時のみ: Codex ではユーザーが subagent / delegation / parallel agent work を明示した場合だけ起動する
• project knowledge は共有: Codex でも .claude/skills/project-standards/SKILL.md と .claude/agent-memory/dev-reviewer/MEMORY.md を読む（Codex 専用 copy は作らない）

8. このスキルの境界

含む: 全プロジェクト共通の最低ライン 含まない: スタック特化規約・プロジェクト固有のドメイン知識・チーム慣習

→ プロジェクト固有のものは .claude/skills/project-standards/SKILL.md に書く（雛形は kit の examples/project-standards-template/ 参照）。このパスは Claude Code と Codex で共有する。