---
name: coding-standards
description: >
  コード・テストコードを新規作成または修正する時、その計画時、コードレビュー時に最初に必ず呼び出すこと。
  コメントの日本語表現は`agent-toolkit:writing-standards`と併用する。
  単に理解のためコードを読むだけの場合や、ドキュメントのみの編集ではトリガー不要。
---

# コーディング品質

本スキルは、コード・テストコードの品質基準を提供する。

## 適用範囲

全プロジェクトへ共通するコーディング規範と、言語横断で照合する標準ツール・構文方針を記述する。
言語・フレームワーク・ライブラリ固有の詳細は、`references/<言語>.md`または
`references/<フレームワーク・ライブラリ名>.md`へ置く。
プロジェクト固有の規約は当該プロジェクトの`CLAUDE.md`・`.claude/rules/`へ置く。

コード編集に着手する前に、編集対象の拡張子に対応する`references/<言語>.md`を必ずReadで読み込む
（変更規模を問わず省略しない。対応ファイルが無い場合に限り共通品質のみで進める）。
プロジェクトの依存定義（`package.json`等）または`<script>`読み込み等の技術利用痕跡から対象技術の利用が判明する場合は、対応する`references/<フレームワーク・ライブラリ名>.md`も読み込む。

言語別リファレンス:

- Python: `references/python.md`と`references/python-references.md`
- TypeScript/TSX: `references/typescript.md`
- Rustのコードを編集する時は`agent-toolkit/skills/coding-standards/references/rust.md`を全文読む
- C#: `references/csharp.md`
- Bash/sh・bash・sh.tmpl: `references/bash.md`
- PowerShell/ps1・ps1.tmpl・psm1・psd1: `references/powershell.md`
- Windowsバッチ/cmd・bat: `references/windows-batch.md`
- Dockerfile: `references/dockerfiles.md`
- GitHub Actionsワークフロー（`.github/workflows/*.yaml`）: `references/github-actions.md`

トピック別リファレンス:

- 依存管理詳細（バージョン固定方針・脆弱性確認・ロックファイル運用・パッケージマネージャー個別の注意点）:
  `references/dependency-management.md`
- 文字エンコーディング詳細（日本語環境・ZIPファイル・Unicode正規化等）: `references/encoding.md`
- 単体HTML成果物（ユーザーへ単体で提示するレポート・ダッシュボード等。作成・修正時に必読）:
  `references/independent-html.md`
- テストコードを作成・修正する時は`agent-toolkit/skills/coding-standards/references/testing.md`を全文読む

フレームワーク・ライブラリ別リファレンス:

- Tailwind CSS（v4系、依存名`tailwindcss`）: `references/tailwindcss.md`
- Alpine.js（v3系、依存名`alpinejs`または`<script>`読み込み）: `references/alpinejs.md`
- Playwright Test（v1系、依存名`@playwright/test`）: `references/playwright.md`
- Drizzle ORM/Drizzle Kit（0.x系、依存名`drizzle-orm`・`drizzle-kit`）: `references/drizzle.md`
- Svelte 5/SvelteKit 2（依存名`svelte`・`@sveltejs/kit`）: `references/svelte.md`

## 言語横断のツールと構文

プロジェクトに指定が無い場合は、次の標準ツールを使う。

| 言語 | 依存管理・ビルド | lint・format・補助ツール |
| --- | --- | --- |
| Python | `uv` | `pyfltr`、`pytilpack` |
| TypeScript | `pnpm`、一度限りの実行は`pnpx` | `Biome`。未対応ルールが必要な場合だけESLintとPrettierを併用 |
| Rust | `cargo` | `cargo clippy -D warnings`、`cargo fmt` |
| C# | `dotnet` CLI | `dotnet format`、Roslynアナライザー、`Microsoft.CodeAnalysis.NetAnalyzers` |
| Bash | 該当なし | `shellcheck`、`shfmt` |
| PowerShell | 該当なし | PSScriptAnalyzer |

公開互換性として宣言した範囲で利用できる新しい言語機能を積極的に使う。
利用可否は対象プロジェクトの言語バージョンと公式リリースノートで確認する。
標準ライブラリで代替できる外部依存は排除する。

シェル系言語では、外部入力をコマンドの引数として渡す。
動的な実行が必要な場合は固定候補へ分岐し、評価系コマンドへ外部入力を渡さない。
外部入力を含むコマンド文字列を組み立てて実行しない。

## コーディング品質（全言語共通）

以下の規範は、01-agent.md「判断指針」の具体例である（網羅規定ではなく、列挙外の場面でも原則に従う）。

### 実装方針の選択

設計判断を確定する時点で`agent-toolkit/skills/coding-standards/references/design-heuristics.md`を全文読む。該当する定石とトレードオフを確認する。

- 実装に着手する前に、以下の順で検討する実装ラダーを適用する
  - 上位で成立する選択肢が見つかった時点で下位の検討は打ち切る
  - 検討順序:
    1. そもそも必要か（YAGNI）
    2. 標準ライブラリで実現できるか
    3. プラットフォーム標準機能（ブラウザAPI・OS提供機能等）で実現できるか
    4. インストール済みの依存で実現できるか
    5. 1行で書くか
    6. 上記いずれも成立しない場合のみ最小限の独自実装
  - ラダー対象外: 信頼境界検証・データ損失防止・セキュリティ・アクセシビリティ・
    ハードウェア較正に関わる実装はラダーで省略せず必要な堅牢性を確保する
- hashを採用する前に、識別・改ざん検知・cache invalidation等の目的、非hashの代替、衝突時の影響を確定する。
  目的に必要な性質を満たす最小の手段を選び、直接比較で十分な場合はhashを使わない（努力目標）
  - 複数の可変長値を入力にする場合は、長さ接頭辞または仕様で一意な正規形式により境界を一意にし、
    異なる値の分割が同じhash入力列にならない反証ケースをテストする（厳守規定）
- 品質要件を満たす実装案は、保守、実行時間、状態・工程、障害影響を含む総ライフサイクルコストで比較する。
  再発防止の便益は評価へ含めるが、既存契約の修正や削除・統合で同じ便益を得られる案を優先する
- 標準仕様のある形式（YAML・JSON・TOML等）を読み書きする実装は、形式のサブセットを自前パースせず正規のパーサーを使う
  （サブセット実装は仕様準拠を保証できず、正当な入力（複数行・入れ子の値など）を静かに誤読・欠落させるため）
- 入力形態の網羅: 集計値の判別条件と、入力形態が複数あり得る解析処理（正規表現・パーサー・突合条件）は、
  対象の命名規則・出力仕様が生成し得る形態を列挙してから確定する。
  構造化データ（frontmatter・JSON等）を対象とする集計では当該構造を解析した結果を根拠とし、
  条件へ合致しなかった対象を個別に確認して該当と非該当を区分する
  （条件の不備による取りこぼしと、構造外の記述への一致による過大計上の双方を防ぐ）。
  既存の解析処理を変更する場合は変更前後の双方を全形態へ適用して差分を比較し、
  変更前に取れていた情報が取れなくなる形態が1件でもあれば当該案を採用しない
- 公開仕様に準拠する解析処理（マークアップ・データ形式・識別子形式などの構文解析）を実装または
  変更する場合、当該仕様の参照実装が利用可能であれば、それを正解として突合し列挙の網羅性を検証する
  （努力目標。自力の列挙は仕様の見落としを検出できないため）
- 自動承認またはポリシー判定に用いる解析処理を新規作成・変更する前に、入力生成主体、信頼境界、
  通常入力、対象外入力、誤許可と誤拒否が消費主体へ与える影響を明示する。実装とテストの入力集合は
  この宣言へ合わせ、宣言外の脅威モデルを暗黙の要件として追加しない

### 記述順序と命名

- トップダウンの記述順序を遵守する。型定義や上位の関数から先に書き、関連するものは近くにまとめ、追記時は
  機械的に末尾へ追加せず既存の定義順序に沿った位置へ挿入する
- 既存ファイルへ新規関数・節・テストケース等を追加する場合、追加先ファイル全体の既存命名規約を観察してから追加する。
  観察対象は関数名のASCII・非ASCIIの別、節名の命名パターン、用語選択を含む。同一ファイル内で命名形式を混在させない

### データと計算

- 計算量を意識し、入力サイズの増大に耐える実装を選ぶ
- 浮動小数点: 金額など正確さが必要な計算には整数演算や専用の十進型を使い、等値比較は許容誤差で行う
- 日時: タイムスタンプはUTC、市民時刻はタイムゾーン情報を保持する（プロジェクト方針が無い場合）。日時演算にはライブラリを使う
- 文字エンコーディング: 入出力境界でエンコーディングを明示し、内部処理ではUTF-8を基本とする
- 乱数: 言語標準APIを使い、シードに予測可能な値を使わない。範囲変換には専用API（`randint`等）を使い、
  剰余での変換は避ける。セキュリティ用途ではCSPRNGを使う
- 整数オーバーフロー: 固定幅整数を扱う言語では、意図しないオーバーフローが生じ得る演算・型変換に
  検査付き演算、より広い型、事前の範囲検証のいずれかを適用する。
  意図的なラップアラウンドは、言語仕様で剰余動作が保証される演算・型、または専用のwrapping演算といった
  実行時に成立する機構で表す（厳守規定。コメントは実行時の演算を変えないため、意図の補足に限り機構の代替にしない）

### リソースと並行処理

- リソース管理: ファイルハンドル・DB接続・ロックなどはRAIIやコンテキストマネージャーで確実に解放する
- 並行処理・非同期処理: 共有状態へのアクセスは適切な同期機構で保護し（可能なら共有状態自体を避け）、
  I/O待ちにはasync/awaitを優先する

### セキュリティ・ロギング・エラー処理

- フレームワーク固有・ライブラリ固有の実装パターンを採用する場合、
  根拠とした公式ドキュメントのURLをコード内コメントへ付記する
- セキュリティ: 信頼境界（外部入力・API応答・ユーザー操作など）を常に意識する
  - 入力検証は型・範囲・形式を検証し許可リスト方式を優先する。
    SQL・コマンド・HTMLなどの実行・解釈文脈への直接結合、
    未正規化のパス構築によるパストラバーサル、信頼できないデータの安全でない復元は避ける
  - シークレットはソースコード・ログに出力しない。プロセス・トークン・DB接続などの権限は必要最小限にし、
    スタックトレース・内部パスなどの内部情報をエンドユーザーへ露出しない
- ロギング: 障害時の原因究明を前提に書き、構造化ログ・相関IDの伝播を推奨する
  - シークレット・個人情報はログに出力しない
- エラー処理: 例外の種別ごとに方針を決めて扱う
  - 一時的エラー（ネットワーク・ロック競合等）はリトライ対象。指数バックオフ + ジッタを基本とする
  - 永続的エラー（入力不正・権限不足等）は即座に失敗させ、呼び出し元に原因を返す
  - プログラマエラー（不変条件違反）はfail-fastで例外を送出し、捕捉して無視してはならない
  - catchは具体的な型に限定し、広域キャッチは境界層に限る。リトライ回数・タイムアウトは設定可能にする
  - 外部状態の取得失敗時に安全側の結論（処理の中止・延期など）を採用する判定では、先に保護対象への
    到達可能性（所有権・権限・アクセス境界など、判定結果へ実際に影響する条件）で母集団を定め、
    母集団内の対象の取得失敗だけを安全側の根拠とする。母集団外の対象の取得失敗を根拠にしない。
    母集団と取得失敗時の扱いを定めた後、実環境の入力に対して当該結論が常時成立しないことを実測で確認する
    （厳守規定。母集団を定めずに取得失敗を安全側の根拠とすると、判定と無関係な対象の取得失敗によって
    結論が常時成立し、当該機能を恒久的に停止させる）

### 依存と自動生成物

- 設定ファイルへの変更に専用CLIがある場合は手編集より優先する（`uv add`/`pnpm`/`mise`等）
- 依存の追加・更新は上記の専用CLIで行い、ロックファイルとマニフェストを同期させる。
  バージョン固定・脆弱性確認・ロックファイル運用の詳細は`references/dependency-management.md`に従う
- 自動生成ファイル（依存ロックファイル・`*_pb2.py`等の自動生成コード・ビルド成果物・補完スクリプト等）は直接編集しない
  - 更新は生成元（`pyproject.toml`・`package.json`・`.proto`等）または専用CLI
   （`uv add`・`pnpm add`・`cargo update`等）経由で行う
  - 直接編集が必要と判断される場合は、生成元側の設定変更で表現できないかをまず検討する
- エンドユーザーが蓄積したデータ（ファイル配置・ファイル形式・スキーマ・設定形式）を変更する場合、
  旧形式から新形式への移行処理を同一の変更へ含める
  - 移行をエンドユーザーの手作業へ委ねる設計は採用しない
  - 移行処理を含められない技術的制約がある場合に限り、拒否時の案内文へエンドユーザーが単独で完遂できる手順を書く
  - 案内文で外部の状態変更を要求する場合は、その状態を当該変更の実装者が用意したうえで書く
- 既存コードの意図的な制約（型制約・アクセス制限・lint設定・不変条件のアサーション等）を新規コードの都合で除去・緩和しない。
  制約の変更が必要と判断した場合は先にその必要性を検証する
- 移行処理と案内出力が同じ対象を扱う場合は判定関数を共有し、移行成立後に案内が自動的に無効化される条件を持たせる

### lintと機械チェック

- lintエラーへの対応は以下の優先順で検討する
  1. コード修正（ルールが正当な問題を指摘している場合）
  2. コードの書き方の変更（del・assert・型の明示など、軽微な変更で解消できる場合）
  3. インライン無視コメント（ユーザーによる確認必須）: コードが意図的で、その箇所だけルールの当てはまらない場合に使う。
     理由が自明でなければ理由を併記する
  4. 設定ファイルでの抑制（ユーザーによる確認必須）: ルールがプロジェクト方針と合わない、
     または同一の抑制が繰り返し必要になる場合
  - 振る舞いを変えずlintの指摘だけを回避するコード変更は避ける
  - ファイル全体一括の抑制コメント（行数・複雑度・メソッド数等の上限を一括無視するコメント）の
    新規追加は採用しない。該当ファイルが過大化している場合は責務境界・シナリオ群でのファイル分割を優先する
  - 抑制コメントの新規追加時は、同ファイル内・同種ファイルにある既存の抑制コメントとは独立に本節の判断基準を適用する
  - プロジェクト方針でlinter／formatterのファイル個別実行がサポートされている場合は、
    変更対象ファイルへ事前実行し自動修正可能な指摘をその場で対応する（具体コマンドはプロジェクト方針に従う。例: `pyfltr`等）
- lintルール・機械チェックを新規に有効化・強化する変更は、着手前に既存コードへの検出結果をトリアージする工程を対応方針へ含める。
  区分は「共通化・修正すべき是正対象」と「意図的な設計による許容対象（理由コメント付き抑制等で対処）」とし、
  検出の全件を一律に是正対象または一律に抑制対象と扱わない
  - 例: `pylint`の`duplicate-code`では、同期・非同期の並行実装やプラットフォームペア実装間の類似が意図的な許容に該当し得る

### エンドユーザー接点と公開インターフェース

- CLIメッセージ設計: エンドユーザー向けエラーメッセージ・案内文は現行仕様のみで理解できる文面とし、
  metavar・内部識別子ではなくエンドユーザーの操作に即した平易な語を使う
- モジュール内および隣接モジュール（同ディレクトリ配下、または共通の公開インターフェースを介する
  呼び出し関係にあるモジュール群）の命名規約・エラー処理方針・返却値構造の一貫性を保つ
- 公開インターフェースを変更する場合、連動追従が必要な次の対象を、
  変更した識別子・出力文字列の全文検索（`grep`等）で全件洗い出す。
  公開インターフェースとはAPI・UI、CLIオプション・設定形式・出力形式、ライブラリの公開関数・
  公開クラス・データ形式など配布物のエンドユーザーが直接触れる面を指す
  （リポジトリ内部のモジュール・関数・クラスはpublic修飾の有無を問わず内部実装として扱う）
  - 対応する単体テスト・統合テスト・スナップショット
  - 対応するドキュメント（エンドユーザー向け・開発者向け）・サンプルコード・出力例
  - 対応する利用元（配布物を利用する側のコード・スクリプト、または内部で公開インターフェースを呼び出すモジュール群）
  - エンドユーザー向けエラーメッセージ・案内文