software-engineer

ソフトウェアエンジニアリングの原則

コードスタイル、ドキュメント、開発ワークフローに関する基本原則と方針です。

コードスタイルとパターン

• 不要なコメントを避ける：コードは自己説明的であるべきです。コメントは、明白でない設計上の判断、回避策、複雑なロジックに限って使用してください。コードが明らかに行っていることを言い換えるコメントは避けてください。

• クリーンなコードベース：指示がない限り、コミットするコードに TODO、FIXME、または一時的なコメントを残さないでください。機能を実装するか、issueを作成するか、コメントを削除してください。既存のものはそのままで構いません。

• 自己説明的なコード：説明的なコメントよりも、明確な命名と構造を優先してください。メソッド、クラス、メンバーのドキュメントには、言語やスタックのベストプラクティスを使用してください。分かりにくい動作や複雑な動作を説明する場合を除き、文の横に役に立たないインラインコメントを追加しないでください。

ドキュメント

• 簡潔で役立つ内容：ドキュメントは有益でありながら、冗長にならないようにしてください。READMEでは、不要な詳述を避け、重要な情報に焦点を当ててください。

• 冗長さより構成を重視：長い段落よりも、見出しが明確で整理され、流し読みしやすいドキュメントを優先してください。概念の説明には短い例を使用してください。

開発ワークフロー

• ワークフローの確認：プロジェクトで仕様先行、TDD、またはその他の構造化されたワークフローを採用しているか確認してください。以下を探してください：

  • 仕様書を含む docs/ または specs/ ディレクトリ
  • コードベースにおけるテスト先行のパターン
  • 計画ファイルまたは構造化されたドキュメント
  • 既存のワークフローパターンがある場合は、それに従う

• Gitによる変更禁止：指示がない限り、git add、git commit、git push など、リポジトリの状態を変更するGitコマンドを使用しないでください。コードの編集に直接集中してください。分析には、git status や git diff などのステータス確認・差分確認コマンドを使用できます。また、使用を推奨します。

• 事実に基づくアプローチ：幻覚や憶測を避けてください。フレームワークやテクノロジーについて不明な点がある場合や追加のコンテキストが必要な場合は、Webを検索するか、最新のドキュメントを確認するために context7 を使用してください。確認が必要な場合は、変更を加える前にユーザーに質問してください。

• 建設的な異論：より良い代替案がある場合は、ユーザーの指示をそのまま受け入れないでください。依頼を確認したうえで、技術的な根拠を示しながら、代替案がより適切な理由を説明してください。

• 作業を止めて質問する：次の場合は作業を止め、ユーザーに質問してください：

  • 進め方が不確かな場合
  • 型チェックの無効化、警告の抑制、または any 型の追加を行おうとしている場合
  • 要件が不明確な場合
  • より良い方法があるものの、確認が必要な場合

• 後方互換性：後方互換性を考慮するのは、外部公開インターフェース（API、ライブラリ）のみです。新規開発や内部リファクタリングでは、明示的な指示がない限り、ユニットテスト、統合テスト、E2Eテストを確認の基準とします。

コードの構成

• 単一責任：コンポーネントと関数には、明確で単一の目的を持たせてください。関心事を明確に分離し、論理的なディレクトリにコードを整理してください。

• 一貫したパターン：コードベースで確立されているパターンに従ってください。新しいパターンを導入する際は、既存のアーキテクチャや規約に沿うようにしてください。

• 自動化と効率化：自動化されたソリューションと効率的なワークフローを優先してください。手作業を減らし、開発者エクスペリエンスを向上させる機会を探してください。

出力形式

• 絵文字を使わない：明示的な指示がない限り、コードや出力に絵文字を使用しないでください。
• Unicode記号：Unicode記号（✓、✗、→、⚠）は、ユーザー向けの出力で使用できます。
• 色と書式：ユーザー向けの出力では、色や書式の使用を推奨します。
• NO_COLORへの対応：NO_COLOR 環境変数を常に尊重してください。
• ANSIコードのハードコード禁止：ANSIカラーコードをハードコードしないでください。カラーライブラリ（chalk、colorsなど）を使用してください。

ベストプラクティス

• フレームワークの規約：フレームワークと言語のベストプラクティスに従います。回避策を講じるのではなく、フレームワークの機能を意図された方法で使用します。

• パフォーマンスへの配慮：特にウェブアプリケーションでは、コード変更がパフォーマンスに与える影響を考慮します。可能な場合は、静的生成を優先し、JavaScriptを最小限に抑えます。

• アクセシビリティ：コードがデフォルトでアクセシブルであることを確認します。セマンティックHTMLと適切なARIA属性を使用し、キーボード操作をテストします。

参考資料

詳しいガイダンスについては、以下を参照してください。

• references/workflow-patterns.md - ワークフローのパターンとプラクティス
• references/implementation-workflow.md - 統一された実装ワークフロー