From b2860483baf8a23ebb9d052cde73681815f83979 Mon Sep 17 00:00:00 2001
From: wasyokusatoshi <133361765+wasyokusatoshi@users.noreply.github.com>
Date: Sat, 4 Oct 2025 20:14:32 +0900
Subject: [PATCH] docs: Add ESLint and code style guidelines to DEVELOPMENT.md

- Added detailed ESLint configuration information to DEVELOPMENT.md (both EN and JA)

- Added reference links from CONTRIBUTING.md to DEVELOPMENT.md

- Documented linting commands, pre-commit hooks, and review standards

Fixes #1299
---
 CONTRIBUTING.md        |  4 ++++
 docs/en/DEVELOPMENT.md | 45 ++++++++++++++++++++++++++++++++++++++++++
 docs/ja/DEVELOPMENT.md | 45 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 94 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d0649a77a..2a8e7e5b9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -35,6 +35,10 @@ To send us a pull request, please:
 5. Send us a pull request, answering any default questions in the pull request interface.
 6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
 
+For detailed development guidelines including linting and code style requirements, please refer to:
+- [DEVELOPMENT.md (English)](docs/en/DEVELOPMENT.md)
+- [DEVELOPMENT.md (日本語)](docs/ja/DEVELOPMENT.md)
+
 GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
 [creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
 
diff --git a/docs/en/DEVELOPMENT.md b/docs/en/DEVELOPMENT.md
index 0a671574f..b150e7f1b 100644
--- a/docs/en/DEVELOPMENT.md
+++ b/docs/en/DEVELOPMENT.md
@@ -52,6 +52,45 @@ npm run web:dev
 
 If executed successfully, it will start at http://localhost:5173, so please try accessing it from your browser.
 
+## Linting and Code Style
+
+This project uses **ESLint** and **Prettier** to enforce code quality and consistent style.
+
+### ESLint Configuration
+
+- **Config files**: ESLint configurations are located in each package directory:
+  - `packages/web/.eslintrc.cjs` (Frontend)
+  - `packages/cdk/.eslintrc.cjs` (CDK/Infrastructure)
+  - `browser-extension/.eslintrc.json` (Browser Extension)
+- **Base rules**: We extend commonly used configs:
+  - `eslint:recommended`
+  - `plugin:@typescript-eslint/recommended`
+  - `plugin:react-hooks/recommended` (for React code)
+  - `plugin:tailwindcss/recommended` (for frontend)
+- **Key rules enforced**:
+  - Unused imports/variables
+  - React Hooks rules (e.g., `exhaustive-deps`)
+  - Japanese string detection (i18n compliance)
+  - YAML formatting and key sorting
+
+### Running ESLint
+
+Before committing, run:
+
+```bash
+npm run lint
+```
+
+To automatically fix issues:
+
+```bash
+npm run web:lint:fix  # For frontend code
+```
+
+### Pre-commit Hook
+
+This repository uses [Husky](https://typicode.github.io/husky) for git hooks. Linting runs automatically on `git commit` via `lint-staged`.
+
 ## When Submitting a Pull Request
 
 We welcome Pull Requests for bug fixes and feature improvements :tada:
@@ -72,6 +111,12 @@ If you want to ignore this error and create a Draft PR, add the `--no-verify` op
 git commit -m "xxx" --no-verify
 ```
 
+### Review Standards
+
+- Lint rules are used as **review criteria**.
+- Please ensure your code passes linting before opening a PR to avoid unnecessary review cycles.
+- Consistent style improves readability and reduces back-and-forth in code review.
+
 Also, if there are changes to the CDK, check the snapshots with the following command and update them:
 
 ```bash
diff --git a/docs/ja/DEVELOPMENT.md b/docs/ja/DEVELOPMENT.md
index 91a466b5c..7276975ff 100644
--- a/docs/ja/DEVELOPMENT.md
+++ b/docs/ja/DEVELOPMENT.md
@@ -53,6 +53,45 @@ npm run web:dev
 
 正常に実行されれば http://localhost:5173 で起動しますので、ブラウザからアクセスしてみてください。
 
+## Lint とコードスタイル
+
+このプロジェクトでは、コード品質と一貫したスタイルを保つために **ESLint** と **Prettier** を使用しています。
+
+### ESLint の設定
+
+- **設定ファイルの場所**: ESLint の設定は各パッケージディレクトリに配置されています:
+  - `packages/web/.eslintrc.cjs` (フロントエンド)
+  - `packages/cdk/.eslintrc.cjs` (CDK/インフラ)
+  - `browser-extension/.eslintrc.json` (ブラウザ拡張)
+- **ベースルール**: 以下の一般的な設定を拡張しています:
+  - `eslint:recommended`
+  - `plugin:@typescript-eslint/recommended`
+  - `plugin:react-hooks/recommended` (React コード用)
+  - `plugin:tailwindcss/recommended` (フロントエンド用)
+- **主要なルール**:
+  - 未使用のインポート/変数の検出
+  - React Hooks のルール (例: `exhaustive-deps`)
+  - 日本語文字列の検出 (i18n 対応)
+  - YAML のフォーマットとキーのソート
+
+### ESLint の実行
+
+コミット前に以下を実行してください:
+
+```bash
+npm run lint
+```
+
+自動修正を行う場合:
+
+```bash
+npm run web:lint:fix  # フロントエンドコード用
+```
+
+### Pre-commit フック
+
+このリポジトリでは [Husky](https://typicode.github.io/husky) を使用して Git フックを管理しています。`git commit` 時に `lint-staged` 経由で自動的に lint が実行されます。
+
 ## Pull Request を出す場合
 
 バグ修正や機能改善などの Pull Request は歓迎しております :tada:
@@ -73,6 +112,12 @@ npm run web:dev
 git commit -m "xxx" --no-verify
 ```
 
+### レビュー基準
+
+- Lint ルールは**レビュー基準**として使用されます。
+- 不要なレビューサイクルを避けるため、PR を開く前にコードが lint を通過することを確認してください。
+- 一貫したスタイルは可読性を向上させ、コードレビューでのやり取りを減らします。
+
 もしCDK に変更があれば以下のコマンドでスナップショットの確認を行いスナップショットを更新してください。
 
 ```bash