file-name-wizard

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Filename & Naming Convention Audit

文件名与命名规范审计

Instructions

操作说明

Perform systematic audit of all filenames and naming conventions in the codebase to identify inconsistencies, anti-patterns, and violations of naming standards.

对代码库中所有文件名与命名规范进行系统性审计，识别不一致问题、反模式以及对命名标准的违反情况。

Phase 1: Discovery & Standard Extraction

第一阶段：发现与标准提取

Step 1: Find All Files

步骤1：查找所有文件

Use Glob to identify all files in the codebase:

Source files (
```
.ts
```
,
```
.tsx
```
,
```
.js
```
,
```
.jsx
```
, etc.)
Config files
Documentation files
Test files

Create comprehensive todo list of all files to audit.

使用Glob识别代码库中的所有文件：

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

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

Step 2: Extract Naming Standards

步骤2：提取命名标准

Read all

AGENTS.md

files in the repository:

Root
```
AGENTS.md
```
if exists
Directory-specific
```
AGENTS.md
```
files

Extract naming conventions:

File naming patterns (kebab-case, PascalCase, etc.)
Directory structure rules
Component naming rules
Utility/helper naming rules
Test file naming rules
Config file naming rules
Constant/enum file naming rules

读取仓库中所有

AGENTS.md

文件：

根目录下的
```
AGENTS.md
```
（若存在）
各目录专属的
```
AGENTS.md
```
文件

提取命名规范：

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

Step 3: Identify Implicit Patterns

步骤3：识别隐含模式

Even without explicit AGENTS.md rules, identify patterns:

Most common naming convention in each directory
Grouping patterns (e.g.,
```
*.service.ts
```
,
```
*.controller.ts
```
)
Organizational patterns (e.g.,
```
components/
```
,
```
utils/
```
,
```
lib/
```
)

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

每个目录中最常用的命名规范
分组模式（如
```
*.service.ts
```
、
```
*.controller.ts
```
）
组织模式（如
```
components/
```
、
```
utils/
```
、
```
lib/
```
）

Phase 2: Systematic File Audit

第二阶段：系统性文件审计

For EACH file in the todo list:

对待办清单中的每个文件执行以下操作：

Step 1: Analyze Filename

步骤1：分析文件名

What is the current filename?
What naming convention does it use?
Is it descriptive and clear?
Does it match its purpose/content?

当前文件名是什么？
它使用了哪种命名规范？
文件名是否具有描述性且清晰？
文件名是否与其用途/内容匹配？

Step 2: Check Against Standards

步骤2：对照标准检查

Compare to:

Explicit AGENTS.md rules for this directory
Implicit patterns in the same directory
Common naming conventions for file type
Best practices for the framework/language

与以下内容进行对比：

该目录下明确的AGENTS.md规则
同一目录中的隐含模式
对应文件类型的通用命名规范
所用框架/语言的最佳实践

Step 3: Identify Issues

步骤3：识别问题

Naming Convention Violations:

Wrong case (e.g., PascalCase when should be kebab-case)
Mixed conventions (e.g.,
```
userAuth.service.ts
```
mixing camelCase and dot notation)
Inconsistent with directory pattern

Clarity Issues:

Vague names (e.g.,
```
utils.ts
```
,
```
helpers.ts
```
,
```
stuff.ts
```
)
Overly verbose names
Misleading names (content doesn't match name)
Abbreviations without context

Anti-Patterns:

Temporary names (e.g.,
```
temp.ts
```
,
```
test.ts
```
,
```
new-*.ts
```
,
```
*-v2.ts
```
)
Generic names (e.g.,
```
index2.ts
```
,
```
common.ts
```
)
Dated names (e.g.,
```
old-*.ts
```
,
```
legacy-*.ts
```
)
Feature flag names (e.g.,
```
*-new.ts
```
,
```
*-enhanced.ts
```
)

Organizational Issues:

File in wrong directory
Missing grouping suffix (e.g., should be
```
*.service.ts
```
)
Inconsistent with sibling files

命名规范违反：

大小写错误（如应使用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
```
）
与同目录其他文件不一致

Step 4: Check File Contents

步骤4：检查文件内容

Read the file to verify:

Does filename accurately describe contents?
Would a better name exist based on what's inside?
Are there naming conventions violations inside (class names, etc.)?

读取文件以验证：

文件名是否准确描述内容？
根据文件内容是否有更合适的名称？
文件内部是否存在命名规范违反（如类名等）？

Step 5: Record Findings

步骤5：记录发现结果

Store in memory:

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]

在内存中存储以下信息：

文件：path/to/filename.ts
使用的规范：camelCase
应使用的规范：kebab-case
模式：违反目录规范
问题：
- [具体问题]
建议名称：[better-name.ts]
严重程度：[HIGH|MEDIUM|LOW]

Step 6: Update Todo

步骤6：更新待办清单

Mark file as audited in todo list.

在待办清单中标记该文件已完成审计。

Phase 3: Pattern Analysis

第三阶段：模式分析

After auditing all files:

完成所有文件审计后：

Step 1: Identify Systemic Issues

步骤1：识别系统性问题

Which directories have most inconsistencies?
What naming patterns are most violated?
Are there clusters of similar violations?

哪些目录的不一致问题最多？
哪些命名模式最常被违反？
是否存在同类违规的集群？

Step 2: Find Outliers

步骤2：找出异常项

Files that don't match any pattern
One-off naming schemes
Orphaned file types

不符合任何模式的文件
一次性命名方案
孤立的文件类型

Step 3: Detect Missing Standards

步骤3：检测缺失的标准

Directories lacking clear naming conventions
File types without established patterns
Areas needing AGENTS.md documentation

缺乏明确命名规范的目录
未建立模式的文件类型
需要在AGENTS.md中补充文档的领域

Phase 4: Generate Report

第四阶段：生成报告

Create report at

.audits/naming-audit-[timestamp].md

markdown

undefined

在

.audits/naming-audit-[timestamp].md

路径下创建报告：

markdown

undefined

Filename & Naming Convention Audit

文件名与命名规范审计

Date: [timestamp] Files Audited: X Issues Found: Y

日期：[timestamp] 已审计文件数：X 发现问题数：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)

关键问题：X个（阻碍一致性）
高优先级：Y个（严重违反）
中优先级：Z个（轻微不一致）
低优先级：W个（建议项）

问题最多的目录：[path]（X个问题）

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
```

```
src/services/auth-v2.ts
```
- 仍在使用的迁移文件
- 违反规则：禁止使用版本后缀
- 建议名称：
```
src/services/auth.ts
```
  （替换旧文件）
```
src/utils/new-logger.ts
```
- 临时命名
- 违反规则：禁止使用"new-"前缀
- 建议名称：
```
src/utils/logger.ts
```

Wrong Case Convention

大小写规范错误

src/components/UserProfile.tsx

- PascalCase

Directory Standard: kebab-case
Suggested:
```
src/components/user-profile.tsx
```

src/components/UserProfile.tsx

- PascalCase

目录标准：kebab-case
建议名称：
```
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
```

```
src/services/database.ts
```
- 缺少
```
.service.ts
```
后缀
- 模式要求：目录中所有文件需使用
```
*.service.ts
```
  后缀
- 建议名称：
```
src/services/database.service.ts
```

Vague/Generic Names

模糊/通用名称

```
src/utils/helpers.ts
```
- Too generic
- Contains: String manipulation functions
- Suggested:
```
src/utils/string-helpers.ts
```

```
src/utils/helpers.ts
```
- 过于通用
- 文件内容：字符串处理函数
- 建议名称：
```
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
```

```
src/lib/validator.ts
```
- 命名为单一用途
- 文件内容：包含多个验证器和格式化工具
- 建议方案：拆分文件或重命名为
```
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
```

src/components/user-authentication-form-component.tsx

冗余问题：组件目录中无需添加"component"后缀
建议名称：
```
src/components/user-auth-form.tsx
```

Issues by Directory

按目录分类的问题

src/services/ (12 issues)

src/services/（12个问题）

Pattern: Should use
```
*.service.ts
```
suffix
Violations:
- ```
database.ts
```
  (missing suffix)
- ```
auth-helper.ts
```
  (wrong suffix)
- ```
userService.ts
```
  (wrong case)

模式要求：需使用
```
*.service.ts
```
后缀
违规项：
- ```
database.ts
```
  （缺少后缀）
- ```
auth-helper.ts
```
  （后缀错误）
- ```
userService.ts
```
  （大小写错误）

src/components/ (8 issues)

src/components/（8个问题）

Pattern: kebab-case without suffix
Violations:
- ```
UserProfile.tsx
```
  (PascalCase)
- ```
button-component.tsx
```
  (redundant suffix)

[Continue for all directories]

模式要求：使用kebab-case且无后缀
违规项：
- ```
UserProfile.tsx
```
  （PascalCase）
- ```
button-component.tsx
```
  （冗余后缀）

[按此格式继续列出所有目录]

Pattern Analysis

模式分析

Most Common Violations

最常见的违规类型

Mixed case conventions - 15 files
Missing pattern suffixes - 12 files
Generic names - 8 files
Temporary names - 5 files

混合大小写规范 - 15个文件
缺少模式后缀 - 12个文件
通用名称 - 8个文件
临时名称 - 5个文件

Directories Lacking Standards

缺乏标准的目录

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

```
src/lib/
```
- 无明确规范（混合使用所有模式）
```
src/shared/
```
- 组织方式不一致
```
tools/
```
- 未建立模式

Emerging Anti-Patterns

新出现的反模式

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

出现版本后缀（
```
*-v2
```
、
```
*-new
```
）
组件文件名中包含"component"
服务文件缺少
```
.service.ts
```
后缀

AGENTS.md Coverage

AGENTS.md覆盖情况

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

✅
```
src/components/
```
- 在
```
src/AGENTS.md
```
中有记录
✅
```
src/services/
```
- 在
```
src/AGENTS.md
```
中有记录
❌
```
src/lib/
```
- 无文档记录
❌
```
src/utils/
```
- 无文档记录
❌
```
tools/
```
- 无文档记录

Missing Documentation Needed

需要补充的文档

File naming conventions for
```
src/lib/
```
Grouping patterns for utilities
Test file naming standards
Config file organization rules

```
src/lib/
```
的文件命名规范
工具函数的分组模式
测试文件的命名标准
配置文件的组织规则

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

按问题类型：

大小写违规：X个
模式违规：Y个
通用名称：Z个
临时名称：W个
误导性名称：V个

按严重程度：

关键：X个
高优先级：Y个
中优先级：Z个
低优先级：W个

按文件类型：

TypeScript：X个问题
React组件：Y个问题
测试文件：Z个问题
配置文件：W个问题

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

文件	问题	建议名称	原因
`src/auth-v2.ts`	版本后缀	`src/auth.ts`	不允许使用迁移文件
`src/UserProfile.tsx`	大小写错误	`src/user-profile.tsx`	目录要求使用kebab-case

High Priority Issues

高优先级问题

[Similar table]

[类似表格]

Medium Priority Issues

中优先级问题

[Similar table]

[类似表格]

Low Priority Issues

低优先级问题

[Similar table]

undefined

[类似表格]

undefined

Phase 5: Summary for User

第五阶段：向用户提供摘要

Provide concise summary:

markdown

undefined

提供简洁的摘要：

markdown

undefined

Naming Convention Audit Complete

命名规范审计完成

Overview

概述

Files Audited: X
Issues Found: Y
Directories with Issues: Z

已审计文件数：X
发现问题数：Y
存在问题的目录数：Z

Critical Issues (Immediate Action)

关键问题（需立即处理）

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

X个文件使用版本/迁移后缀（
```
*-v2
```
、
```
*-new
```
）
Y个文件大小写规范错误
Z个文件存放位置错误

Most Problematic Areas

问题最严重的区域

src/services/ - 12 issues (missing
```
.service.ts
```
suffix)
src/components/ - 8 issues (case convention mix)
src/lib/ - 6 issues (no clear standard)

src/services/ - 12个问题（缺少
```
.service.ts
```
后缀）
src/components/ - 8个问题（大小写规范混合）
src/lib/ - 6个问题（无明确标准）

Top Violations

最常见的违规类型

Mixed case conventions: 15 files
Missing pattern suffixes: 12 files
Generic names: 8 files

混合大小写规范：15个文件
缺少模式后缀：12个文件
通用名称：8个文件

Missing Standards

缺失的标准

```
src/lib/
```
lacks naming documentation
```
src/utils/
```
needs pattern definition
Test files need naming standard

Full Report:

.audits/naming-audit-[timestamp].md

undefined

```
src/lib/
```
缺少命名文档
```
src/utils/
```
需要定义模式
测试文件需要命名标准

完整报告：

.audits/naming-audit-[timestamp].md

undefined

Critical Principles

核心原则

NEVER EDIT FILES - This is audit only, not renaming
NEVER SKIP FILES - Audit every file in todo list
DO READ AGENTS.MD - Extract explicit standards first
DO IDENTIFY PATTERNS - Find implicit conventions
DO BE CONSISTENT - Apply same standards across similar files
DO CHECK CONTENTS - Verify name matches file contents
DO TRACK PROGRESS - Update todo list as you audit
DO FLAG ANTI-PATTERNS - Especially temporary/migration names

绝不修改文件 - 此操作仅为审计，不执行重命名
绝不跳过文件 - 审计待办清单中的每个文件
务必阅读AGENTS.MD - 优先提取明确的标准
务必识别模式 - 找出隐含的规范
务必保持一致 - 对同类文件应用相同标准
务必检查内容 - 验证名称与文件内容是否匹配
务必跟踪进度 - 审计完成后更新待办清单
务必标记反模式 - 尤其注意临时/迁移名称

Success Criteria

成功标准

A complete naming audit includes:

All files in codebase audited
All AGENTS.md standards extracted and applied
Implicit patterns identified for each directory
Violations categorized by severity
Systemic issues identified
Missing standards documented
Structured report generated
Statistics and trends analyzed

After completing the audit, follow handbook

15.04

to create

tk

tickets for all surfaced issues.

完整的命名审计需包含：

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

完成审计后，按照手册

15.04

为所有发现的问题创建

tk

工单。