0
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@tzp(tetsuka hiroki)

AIと人間が共存するチーム開発の命名規則管理術

0
Last updated at Posted at 2026-03-18

はじめに

🤔「isModalOpen と showModal どっちが良いんだろう...？」
😅「またAIが違う命名でコード書いてる...💦」
🔧「チーム全体で命名ルールを統一したい！」

そんな悩みはありませんか？

フロントエンド開発でProps命名は避けて通れない問題です。
特に最近はAIが関わる開発も増えて、人間とAIが混在する環境での一貫性が重要になってきました。

先日、プロジェクトで is~ 形式で統一していたのに、AIに実装を任せると毎回 show~ 形式でコードを書かれ、レビューで指摘し続けるという状況に遭遇しました💦

今回は、その実体験から学んだProps命名の統一方法とGitHub AIと協調するルール管理術をシェアします！

同じような命名の悩みを抱えている方や、GitHub Copilot活用時代のチーム開発に興味がある方の参考になれば幸いです🙏

よくあるProps命名の迷い

😵‍💫 代表的な命名パターンの対立

フロントエンド開発で特に激戦区となる命名パターンをまとめてみました：

1. Boolean系Props 

// パターンA: is~ 形式
isModalOpen, isVisible, isLoading, isDisabled

// パターンB: show/hide 形式  
showModal, hideElement, showSpinner, disableButton

// パターンC: can/has 形式
canSubmit, hasError, canEdit, hasPermission

2. イベントハンドラー系 

// パターンA: on~ 形式
onClick, onChange, onSubmit, onDelete

// パターンB: handle~ 形式
handleClick, handleChange, handleSubmit, handleDelete

3. データ系Props 

// パターンA: 単純形
data, items, user, posts

// パターンB: 詳細形
userData, postItems, userInfo, postList

🤯 なぜ統一が難しいのか？

  1. どれも正解に見える：文法的にはどのパターンも正しい
  2. 個人の経験に依存：過去のプロジェクトや学習した内容で好みが分かれる
  3. フレームワークの影響：React、Vue、Angularで微妙に慣習が違う
  4. AIの学習データ：AIも様々なパターンの中から生成してしまう

実際のプロジェクトで起きた問題

📋 我々のプロジェクトのルール 

// 採用していた命名規則
✅ Boolean: is~ 形式
isVisible, isLoading, isDisabled

✅ イベント: on~ 形式  
onClick, onChange, onSubmit

✅ データ: シンプル形式
users, posts, config（ただし複数形・単数形は意味に応じて）

🤖 AI(GitHub Copilot)が引き起こした問題 

// 人間が書いたコード
<Modal isOpen={isModalOpen} onClose={handleClose} />

// Copilotが生成したコード（毎回こんな感じ😅）
<Modal showModal={showModalFlag} handleClose={onCloseModal} />

結果：

  • ✅ 機能的には問題なく動作
  • ❌ 命名ルールがバラバラ
  • ❌ レビューで毎回指摘
  • ❌ 開発効率の低下

😰 発生した具体的な問題

  1. レビュー時間の増加: 毎回命名について議論
  2. 認識の齟齬: 新しいメンバーが混乱
  3. 検索性の低下: 同じような機能のPropsを見つけにくい
  4. Copilotへの再指示: 毎回「プロジェクトルールに従って」と修正依頼

解決策：ルール化と環境整備

🎯 Step 1: チーム内での命名規則決定

まずは明文化された命名規則を策定しました：

## Props命名規則

### Boolean値
- **is + 状態**: `isVisible`, `isLoading`, `isDisabled`
- **接頭語は統一**: `show~`, `has~` は使用しない

### イベントハンドラー  
- **on + 動作**: `onClick`, `onChange`, `onSubmit`
- **内部実装は handle~**: `handleClick` (内部関数用)

### データ・オブジェクト
- **意味が明確な名前**: `user`, `posts`, `config`  
- **冗長な接尾語は避ける**: `userData` ❌, `user` ✅

🔧 Step 2: ESLintルールで自動化 

// .eslintrc.json
{
  "rules": {
    "react/boolean-prop-naming": [
      "error",
      { 
        "rule": "^is[A-Z]([A-Za-z0-9]?)+",
        "message": "Boolean propsはis~形式で命名してください"
      }
    ]
  }
}

🤖 Step 3: AI用の設定ファイル作成

.github/copilot-instructions.md (GitHub Copilot用)

# GitHub Copilot コーディング指示

## Props命名規則

### Boolean値のProps
- **必須**: is~ 形式のみ使用（例: isVisible, isLoading, isDisabled）
- **禁止**: show~, hide~, has~ 形式（例: showModal, hideElement）

### イベントハンドラーのProps
- **必須**: on~ 形式のみ使用（例: onClick, onChange, onSubmit）
- **禁止**: handle~ 形式のProps名（例: handleClickではなくonClickを使用）

### データ系のProps
- **推奨**: シンプルで明確な名前（例: user, posts, config）
- **禁止**: 冗長な接尾語付きの名前（例: userData, postData は避ける）

## コード生成時の注意
- 上記命名規則に必ず従ってコード生成すること
- 既存コードの命名パターンを確認し、一貫性を保つこと
- Boolean値は常にis~で開始すること

📋 Step 4: TypeScript型定義での強制 

// types/props.ts
interface BaseProps {
  // Boolean系は is~ 強制
  readonly [K in `is${string}`]?: boolean;
}

interface EventProps {
  // イベント系は on~ 強制
  readonly [K in `on${string}`]?: (...args: any[]) => void;
}

// 使用例
interface ModalProps extends BaseProps, EventProps {
  isOpen: boolean;      // ✅ ルールに準拠
  onClick: () => void;  // ✅ ルールに準拠
  // showModal: boolean;   // ❌ 型エラー
}

💡 補足: ESLintルールで十分チェックできているので、この型定義による強制はやりすぎ感もあります。ただし、「絶対にこの命名以外は受け付けない」といった強い制約をかけたい場合には有効な手段です👺

運用での工夫とコツ

💡 1. レビューチェックリストの活用 

## Props命名チェックリスト
- [ ] Boolean値は is~ 形式？
- [ ] イベントは on~ 形式？  
- [ ] 冗長な命名になっていない？
- [ ] 既存コードと一貫性がある？

💡 2. IDE設定でのサポート

VS Code settings.json

{
  "emmet.extensionsPath": ".vscode",
  "snippets": {
    "typescript": {
      "boolean-prop": {
        "prefix": "bprop", 
        "body": "is${1:PropName}: boolean;",
        "description": "Boolean prop with is~ naming"
      }
    }
  }
}

💡 3. 新メンバーへのオンボーディング 

// docs/naming-conventions.mdに実例集を作成
## Props命名例

### ✅ Good Examples
<Modal isOpen={true} onClose={handleClose} />
<Button isDisabled={false} onClick={handleSubmit} />
<List items={users} onItemClick={handleUserSelect} />

### ❌ Bad Examples  
<Modal showModal={true} handleClose={handleClose} />
<Button disabled={false} handleClick={handleSubmit} />
<List userData={users} handleItemClick={handleUserSelect} />

実際の効果と成果

📈 導入後の改善結果

導入前：

  • ❌ レビュー時間：命名議論で約5-10分/PR
  • ❌ Copilot生成コード：60%で命名修正が必要
  • ❌ 新メンバー：ルール把握に2-3日

導入後：

  • ✅ レビュー時間：命名関連はほぼゼロ
  • ✅ Copilot生成コード：85%がルール準拠
  • ✅ 新メンバー：半日でルール理解

🎯 特に効果的だった施策

  1. GitHub Copilot設定ファイル: 最も効果的。Copilotが自動的にルールに従うように
  2. ESLintルール: 人間のミスを機械的にキャッチ
  3. 型定義による強制: TypeScriptでコンパイル時にエラー検出

まとめ

🎯 重要なポイント

  1. 明文化の重要性: 口約束ではなく、ドキュメントとして明確化
  2. ツールの活用: ESLint、TypeScript、AI設定で自動化
  3. 継続的な改善: 運用しながら規則をブラッシュアップ
  4. AIとの協調: AI時代には人間とAIが同じルールで動くことが重要

🚀 個人的な学び

今回の経験から：

  • 命名規則の標準化は開発効率を大幅に向上させる
  • AIとのルール共有が想像以上に重要
  • 自動化できる部分は積極的にツール化すべき
  • チーム全体での一貫性が個人の好みより優先

Props命名で悩んでいる方は、ぜひチーム内でのルール策定から始めてみてください！

最後に

Props命名の統一、思っていた以上に開発体験が改善されました💃！

皆さんのチームではどのような命名規則を採用していますか？
GitHub Copilotを活用した開発での工夫があれば、ぜひコメントで教えてください！

命名規則の実例や便利なツール設定なども共有していただければと思います👩‍🌾！

0
2
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?