コーディングガイドライン

このドキュメントは Todo プロジェクトで Python と TypeScript の双方におけるコーディングスタイルおよび開発ルールをまとめたものです。既存のリンターやフォーマッターを尊重しつつ、可読性と保守性を最大化することを目的とします。

共通方針

変更意図をコミットメッセージとコードコメントで明確にする。複雑な処理のみコメントを追加し、冗長な説明は避ける。
型情報を積極的に活用し、CI で発見できる問題はローカルでも早期に検出する。
フォーマッタ（Python: uv run ruff format、TypeScript: npm run lint:fix など）が提供されている場合は必ず適用してからプルリクエストを作成する。
新規機能やバグ修正にはテストを追加し、既存テストが赤になっていないことを確認する。

スタイルは PEP 8 に従い、ruff によるフォーマットとリンティングを基準とする。
可能な限り型ヒントを付与し、mypy などの型チェッカーで検証できる状態を保つ。
関数は単一責務と可読性・保守性を重視し、複雑または読みにくくなった場合はヘルパー関数への分割を検討する（目安として 25 行程度を参考にしてもよいが、厳密な基準ではありません）。
例外は具体的な型で捕捉し、except Exception のような広すぎるキャッチは避ける。
ロギングには標準の logging モジュールを使用し、print によるデバッグ出力は残さない。
テストは pytest を使用し、Arrange-Act-Assert パターンで構造化する。外部 API は pytest-mock でスタブ化し、安定したテストを心掛ける。

スタイルはプロジェクトに定義された ESLint ルールと prettier 設定に従う。
すべての公開 API には明示的な型注釈を付与し、any の使用は必ず // eslint-disable-next-line @typescript-eslint/no-explicit-any と、その直上に「なぜ any が必要か」を説明するコメントの両方を記載した場合のみ許可する。
React コンポーネントは関数コンポーネントを基本とし、useEffect などのフックは依存配列を厳密に管理する。
データ取得や副作用は Service 層やカスタムフックに分離し、UI コンポーネントを薄く保つ。
async/await を使用して非同期処理を記述し、エラーハンドリングには try/catch もしくは Result パターンを採用する。
Playwright などの E2E テストではユーザー操作を基本単位とする。
セレクタはまずロールやラベル、テキストなどアクセシビリティに基づくもの（例: role, accessible name, label）を優先して使用し、どうしても難しい場合のみテスト ID (data-testid) を利用する。

これらのガイドラインは継続的に見直し、プロジェクトの成長に合わせて更新してください。