步骤 3：识别隐式模式

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

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

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

对于待办事项列表中的每个文件：

步骤 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:
- [具体问题]
Suggested Name: [better-name.ts]
Severity: [HIGH|MEDIUM|LOW]

步骤 6：更新待办事项

在待办事项列表中标记文件为已审计。

第三阶段：模式分析

审计完所有文件后：

步骤 1：识别系统性问题

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

步骤 2：找出异常值

• 不匹配任何模式的文件
• 一次性的命名方案
• 孤立的文件类型

步骤 3：检测缺失的标准

• 缺乏明确命名约定的目录
• 没有既定模式的文件类型
• 需要 AGENTS.md 文档的领域

第四阶段：生成报告

创建一个带有 audit 标签的 tk 工单，并将报告作为其正文。使用 todos_oneshot(title: "Audit: Naming conventions", description: "<report content>", tags: "audit", type: "task")。

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

---

## Executive Summary
- **Critical Issues**: X (阻碍一致性)
- **High Priority**: Y (主要违规)
- **Medium Priority**: Z (次要不一致)
- **Low Priority**: W (建议)

**Most Problematic Directory**: [路径] (X 个问题)

---

## Issues by Severity

### CRITICAL: Convention Violations

#### Temporary/Migration Filenames
- `src/services/auth-v2.ts` - 迁移文件仍在使用中
  - **Violates**: No version suffixes rule
  - **Suggested**: `src/services/auth.ts` (替换旧文件)

- `src/utils/new-logger.ts` - 临时命名
  - **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]

第五阶段：用户摘要

提供简洁摘要：

# 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 工单。

Weekly Installs

1.2K

Repository

cygnusfear/agent-skills

First Seen

Feb 13, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

amp1.0K

gemini-cli1.0K

opencode1.0K

codex1.0K

github-copilot1.0K

kimi-cli1.0K

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

Step 3: Identify Implicit Patterns

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/)

Phase 2: Systematic File Audit

For EACH file in the todo list:

Step 1: Analyze Filename

• 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

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

Step 3: Identify Issues

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

Step 4: Check File Contents

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

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]

Step 6: Update Todo

Mark file as audited in todo list.

Phase 3: Pattern Analysis

After auditing all files:

Step 1: Identify Systemic Issues

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

Step 2: Find Outliers

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

Step 3: Detect Missing Standards

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

Phase 4: Generate Report

Create a tk ticket tagged audit with the report as its body. Use 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]

Phase 5: Summary for User

Provide concise summary:

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

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

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.

Weekly Installs

1.2K

Repository

cygnusfear/agent-skills

First Seen

Feb 13, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

amp1.0K

gemini-cli1.0K

opencode1.0K

codex1.0K

github-copilot1.0K

kimi-cli1.0K