file-name-wizard

文件名与命名约定审计

说明

对代码库中的所有文件名和命名约定进行系统审计，以识别不一致、反模式和违反命名标准的情况。

阶段 1：发现与标准提取

步骤 1：查找所有文件

使用 Glob 查找代码库中的所有文件：

• 源文件（.ts、.tsx、.js、.jsx 等）
• 配置文件
• 文档文件
• 测试文件

创建包含所有待审计文件的完整待办清单。

步骤 2：提取命名标准

读取仓库中的所有 AGENTS.md 文件：

• 根目录中的 AGENTS.md（如果存在）
• 目录专属的 AGENTS.md 文件

提取命名约定：

• 文件命名模式（kebab-case、PascalCase 等）
• 目录结构规则
• 组件命名规则
• 工具函数／辅助函数命名规则
• 测试文件命名规则
• 配置文件命名规则
• 常量／枚举文件命名规则

步骤 3：识别隐式模式

即使没有明确的 AGENTS.md 规则，也要识别以下模式：

• 每个目录中最常见的命名约定
• 分组模式（例如，*.service.ts、*.controller.ts）
• 组织模式（例如，components/、utils/、lib/）

阶段 2：系统性文件审计

针对待办清单中的每个文件：

步骤 1：分析文件名

• 当前文件名是什么？
• 使用了哪种命名约定？
• 是否清晰且具有描述性？
• 是否符合文件的用途／内容？

步骤 2：对照标准检查

对照以下内容：

• 此目录适用的明确 AGENTS.md 规则
• 同一目录中的隐式模式
• 此类文件的常见命名约定
• 框架／语言的最佳实践

步骤 3：识别问题

命名约定违规：

• 大小写形式错误（例如，应使用 kebab-case，却使用了 PascalCase）
• 混用命名约定（例如，userAuth.service.ts 混合了 camelCase 和点号命名）
• 与目录中的模式不一致

清晰度问题：

• 名称含糊（例如，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：更新待办清单

在待办清单中将文件标记为已审计。

阶段 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`)

关键原则

• 绝不编辑文件 - 这只是审计，不是重命名
• 绝不跳过文件 - 审计待办清单中的每个文件
• 务必阅读 AGENTS.MD - 先提取明确规定的标准
• 务必识别模式 - 找出隐含约定
• 务必保持一致 - 对类似文件应用相同标准
• 务必检查内容 - 确认名称与文件内容相符
• 务必跟踪进度 - 审计时更新待办清单
• 务必标记反模式 - 尤其是临时名称和迁移名称

成功标准

完整的命名审计包括：

• 审计代码库中的所有文件
• 提取并应用所有 AGENTS.md 标准
• 识别每个目录的隐含模式
• 按严重程度对违规情况进行分类
• 识别系统性问题
• 记录缺失的标准
• 生成结构化报告
• 分析统计数据和趋势

完成审计后，按照手册 15.04 为发现的所有问题创建 tk 工单。