file-name-wizard

ファイル名・命名規則の監査

手順

コードベース内のすべてのファイル名と命名規則を体系的に監査し、不整合、アンチパターン、命名規則違反を特定します。

フェーズ 1：調査と規則の抽出

ステップ 1：すべてのファイルを検索する

Glob を使って、コードベース内のすべてのファイルを特定します。

• ソースファイル（.ts、.tsx、.js、.jsx など）
• 設定ファイル
• ドキュメントファイル
• テストファイル

監査対象となるすべてのファイルを網羅した todo リストを作成します。

ステップ 2：命名規則を抽出する

リポジトリ内のすべての AGENTS.md ファイルを読みます。

• ルートの AGENTS.md（存在する場合）
• ディレクトリ固有の AGENTS.md ファイル

命名規則を抽出します。

• ファイルの命名パターン（kebab-case、PascalCase など）
• ディレクトリ構成のルール
• コンポーネントの命名規則
• ユーティリティ／ヘルパーの命名規則
• テストファイルの命名規則
• 設定ファイルの命名規則
• 定数／列挙型ファイルの命名規則

ステップ 3：暗黙的なパターンを特定する

明示的な AGENTS.md のルールがなくても、次のパターンを特定します。

• 各ディレクトリで最も一般的な命名規則
• グループ化のパターン（例：*.service.ts、*.controller.ts）
• 整理のパターン（例：components/、utils/、lib/）

フェーズ 2：体系的なファイル監査

todo リスト内の各ファイルについて、次の手順を実施します。

ステップ 1：ファイル名を分析する

• 現在のファイル名は何か
• どの命名規則が使われているか
• 説明が明確で分かりやすいか
• 目的／内容に合っているか

ステップ 2：規則に照らして確認する

次の内容と比較します。

• そのディレクトリに適用される明示的な AGENTS.md のルール
• 同じディレクトリ内の暗黙的なパターン
• ファイル種別に応じた一般的な命名規則
• フレームワーク／言語のベストプラクティス

ステップ 3：問題を特定する

命名規則違反：

• 大文字・小文字の誤り（例：kebab-case にすべきところで PascalCase を使用）
• 命名規則の混在（例：camelCase とドット表記が混在する userAuth.service.ts）
• ディレクトリ内のパターンとの不整合

分かりやすさの問題：

• 曖昧な名前（例：utils.ts、helpers.ts、stuff.ts）
• 冗長すぎる名前
• 誤解を招く名前（内容と名前が一致しない）
• 文脈のない略語

アンチパターン：

• 一時的な名前（例：temp.ts、test.ts、new-*.ts、*-v2.ts）
• 汎用的な名前（例：index2.ts、common.ts）
• 古さを示す名前（例：old-*.ts、legacy-*.ts）
• フィーチャーフラグを示す名前（例：*-new.ts、*-enhanced.ts）

整理上の問題：

• 不適切なディレクトリにあるファイル
• グループ化サフィックスの不足（例：*.service.ts にすべき）
• 同じディレクトリ内のファイルとの不整合

ステップ 4：ファイルの内容を確認する

次の点を検証するため、ファイルを読みます。

• ファイル名は内容を正確に表しているか
• 内容に基づくより適切な名前があるか
• クラス名など、ファイル内の命名規則違反があるか

ステップ 5：調査結果を記録する

メモリに保存します。

File: path/to/filename.ts
Convention Used: camelCase
Should Be: kebab-case
Pattern: Violates directory convention
Issues:
- [Specific issue]
Suggested Name: [better-name.ts]
Severity: [HIGH|MEDIUM|LOW]

ステップ 6：todo を更新する

todo リストで、監査済みとしてファイルに印を付けます。

フェーズ 3：パターン分析

すべてのファイルの監査後、次の分析を行います。

ステップ 1：体系的な問題を特定する

• 不整合が最も多いディレクトリはどこか
• 最も多く違反されている命名パターンは何か
• 類似した違反が集中している箇所はあるか

ステップ 2：例外を探す

• どのパターンにも一致しないファイル
• 独自の命名方式を使用しているファイル
• 孤立したファイル種別

ステップ 3：不足している規則を検出する

• 明確な命名規則がないディレクトリ
• 確立されたパターンがないファイル種別
• AGENTS.md による文書化が必要な領域

フェーズ 4：レポートの作成

レポートを本文とする audit タグ付きの tk チケットを作成します。todos_oneshot(title: "Audit: Naming conventions", description: "<report content>", tags: "audit", type: "task") を使います。

# Filename & Naming Convention Audit
**Date**: [timestamp]
**Files Audited**: X
**Issues Found**: Y

---

## Executive Summary
- **Critical Issues**: X (blocks consistency)
- **High Priority**: Y (major violations)
- **Medium Priority**: Z (minor inconsistencies)
- **Low Priority**: W (suggestions)

**Most Problematic Directory**: [path] (X issues)

---

## Issues by Severity

### CRITICAL: Convention Violations

#### Temporary/Migration Filenames
- `src/services/auth-v2.ts` - Migration file still in use
  - **Violates**: No version suffixes rule
  - **Suggested**: `src/services/auth.ts` (replace old one)

- `src/utils/new-logger.ts` - Temporary naming
  - **Violates**: No "new-" prefix rule
  - **Suggested**: `src/utils/logger.ts`

#### Wrong Case Convention
- `src/components/UserProfile.tsx` - PascalCase
  - **Directory Standard**: kebab-case
  - **Suggested**: `src/components/user-profile.tsx`

### HIGH: Consistency Violations

#### Inconsistent with Directory Pattern
- `src/services/database.ts` - Missing `.service.ts` suffix
  - **Pattern**: All files in directory use `*.service.ts`
  - **Suggested**: `src/services/database.service.ts`

#### Vague/Generic Names
- `src/utils/helpers.ts` - Too generic
  - **Contains**: String manipulation functions
  - **Suggested**: `src/utils/string-helpers.ts`

### MEDIUM: Clarity Issues

#### Misleading Names
- `src/lib/validator.ts` - Named as single purpose
  - **Contains**: Multiple validators and formatters
  - **Suggested**: Split or rename to `validators.ts`

### LOW: Suggestions

#### Verbose Names
- `src/components/user-authentication-form-component.tsx`
  - **Redundant**: "component" suffix in components dir
  - **Suggested**: `src/components/user-auth-form.tsx`

---

## Issues by Directory

### src/services/ (12 issues)
- **Pattern**: Should use `*.service.ts` suffix
- **Violations**:
  - `database.ts` (missing suffix)
  - `auth-helper.ts` (wrong suffix)
  - `userService.ts` (wrong case)

### src/components/ (8 issues)
- **Pattern**: kebab-case without suffix
- **Violations**:
  - `UserProfile.tsx` (PascalCase)
  - `button-component.tsx` (redundant suffix)

[Continue for all directories]

---

## Pattern Analysis

### Most Common Violations
1. **Mixed case conventions** - 15 files
2. **Missing pattern suffixes** - 12 files
3. **Generic names** - 8 files
4. **Temporary names** - 5 files

### Directories Lacking Standards
- `src/lib/` - No clear convention (mix of all patterns)
- `src/shared/` - Inconsistent organization
- `tools/` - No established pattern

### Emerging Anti-Patterns
- Version suffixes appearing (`*-v2`, `*-new`)
- Component files with "component" in name
- Service files without `.service.ts` suffix

---

## AGENTS.md Coverage

### Documented Standards
- ✅ `src/components/` - Documented in `src/AGENTS.md`
- ✅ `src/services/` - Documented in `src/AGENTS.md`
- ❌ `src/lib/` - No documentation
- ❌ `src/utils/` - No documentation
- ❌ `tools/` - No documentation

### Missing Documentation Needed
- File naming conventions for `src/lib/`
- Grouping patterns for utilities
- Test file naming standards
- Config file organization rules

---

## Statistics

**By Issue Type**:
- Case Violations: X
- Pattern Violations: Y
- Generic Names: Z
- Temporary Names: W
- Misleading Names: V

**By Severity**:
- Critical: X
- High: Y
- Medium: Z
- Low: W

**By File Type**:
- TypeScript: X issues
- React Components: Y issues
- Test Files: Z issues
- Config Files: W issues

---

## Detailed File List

### Critical Issues
| File | Issue | Suggested Name | Reason |
|------|-------|----------------|--------|
| `src/auth-v2.ts` | Version suffix | `src/auth.ts` | Migration files not allowed |
| `src/UserProfile.tsx` | Wrong case | `src/user-profile.tsx` | Directory uses kebab-case |

### High Priority Issues
[Similar table]

### Medium Priority Issues
[Similar table]

### Low Priority Issues
[Similar table]

フェーズ 5：ユーザー向けの要約

簡潔な要約を提示します。

# Naming Convention Audit Complete

## Overview
- **Files Audited**: X
- **Issues Found**: Y
- **Directories with Issues**: Z

## Critical Issues (Immediate Action)
- X files with version/migration suffixes (`*-v2`, `*-new`)
- Y files with wrong case convention
- Z files in wrong locations

## Most Problematic Areas
1. **src/services/** - 12 issues (missing `.service.ts` suffix)
2. **src/components/** - 8 issues (case convention mix)
3. **src/lib/** - 6 issues (no clear standard)

## Top Violations
- Mixed case conventions: 15 files
- Missing pattern suffixes: 12 files
- Generic names: 8 files

## Missing Standards
- `src/lib/` lacks naming documentation
- `src/utils/` needs pattern definition
- Test files need naming standard

**Full Report**: tk ticket (tagged `audit`)

重要な原則

• ファイルを編集しないでください — これは監査であり、名前の変更ではありません
• ファイルを省略しないでください — TODO リストにあるすべてのファイルを監査してください
• AGENTS.MD を必ず読んでください — まず明示的な基準を抽出してください
• パターンを特定してください — 暗黙の規則を見つけてください
• 一貫性を保ってください — 類似するファイルには同じ基準を適用してください
• 内容を確認してください — 名前がファイルの内容と一致することを確かめてください
• 進捗を追跡してください — 監査の進行に合わせて TODO リストを更新してください
• アンチパターンを指摘してください — 特に一時的な名前や移行用の名前に注意してください

完了条件

命名監査を完了するには、次のすべてを満たす必要があります。

• コードベース内のすべてのファイルを監査している
• すべての AGENTS.md の基準を抽出し、適用している
• 各ディレクトリの暗黙のパターンを特定している
• 違反を重大度別に分類している
• システム全体にわたる問題を特定している
• 不足している基準を記録している
• 構造化されたレポートを作成している
• 統計と傾向を分析している

監査が完了したら、ハンドブック 15.04 に従って、明らかになったすべての問題について tk チケットを作成してください。