code-naming-auditor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

代码命名审计 Skill (Code Naming Auditor)

Code Naming Auditor Skill

本 Skill 指导一个 AI Agent 对代码库执行全面的审计，以确保其遵循一套明确定义的术语和命名规范。其核心目标是在整个项目中强制执行“通用语言”（Ubiquitous Language），从而提高代码的清晰度、一致性和可维护性。

在使用本 Skill 期间，Agent 的输出避免 Markdown Table 格式。使用无格式文本列表即可。

This Skill guides an AI Agent to perform a comprehensive audit of a codebase to ensure it adheres to a clearly defined set of terminology and naming conventions. Its core goal is to enforce a "Ubiquitous Language" across the entire project, thereby improving code clarity, consistency, and maintainability.

During the use of this Skill, the Agent's output should avoid Markdown Table format. Use unformatted text lists instead.

工作流 (Workflow)

Workflow

审计过程遵循一个结构化的、分步骤的工作流。

The audit process follows a structured, step-by-step workflow.

第一步：建立术语表 (Establish the Glossary)

Step 1: Establish the Glossary

清晰、明确的术语表是所有代码审计工作的基础。

检查现有术语表: 首先，在项目中搜索一个已存在的术语文档。在
```
docs/
```
或根目录中寻找名为
```
glossary.md
```
、
```
terminology.md
```
或类似的文件。
与用户确认: 如果找到了文档，需向用户展示并确认它是否是本次审计工作的“事实之源”（source of truth）。
创建新术语表: 如果项目中不存在术语表，应告知用户其重要性。使用位于
```
references/glossary_template.md
```
的模板来引导用户创建一个。术语表应精确定义项目核心的名词 (Nouns) (例如
```
Content
```
,
```
Section
```
,
```
Line
```
) 和动词 (Verbs) (例如
```
get
```
,
```
find
```
,
```
search
```
,
```
list
```
) 的语义。定义术语表的时候，要考虑使用精确、足够特殊的命名；避免模糊或歧义的术语。

在拥有一个清晰且双方同意的术语表之前，不应继续下一步。

A clear, unambiguous glossary is the foundation of all code audit work.

Check for existing glossary: First, search the project for an existing terminology document. Look for files named
```
glossary.md
```
,
```
terminology.md
```
, or similar in the
```
docs/
```
directory or root directory.
Confirm with the user: If a document is found, present it to the user and confirm whether it is the "source of truth" for this audit work.
Create a new glossary: If no glossary exists in the project, inform the user of its importance. Use the template located at
```
references/glossary_template.md
```
to guide the user in creating one. The glossary should precisely define the semantics of the project's core Nouns (e.g.,
```
Content
```
,
```
Section
```
,
```
Line
```
) and Verbs (e.g.,
```
get
```
,
```
find
```
,
```
search
```
,
```
list
```
). When defining the glossary, consider using precise, sufficiently specific names; avoid vague or ambiguous terms.

Do not proceed to the next step until a clear and agreed-upon glossary is in place.

第二步：定义审计范围 (Define the Audit Scope)

Step 2: Define the Audit Scope

询问用户: 提示用户指定他们希望审计的目录或文件。
确认范围: 在继续之前，与用户确认范围。例如：“我将审计
```
src/basics/
```
目录下的所有文件。这样对吗？”

Ask the user: Prompt the user to specify the directories or files they wish to audit.
Confirm the scope: Confirm the scope with the user before proceeding. For example: "I will audit all files in the
```
src/basics/
```
directory. Is this correct?"

第三步：分析与报告 (Analyze and Report)

Step 3: Analyze and Report

这是核心执行阶段。系统地分析在已定义范围内的每一个文件。

读取文件: 一次读取一个文件内容。
分析命名: 仔细检查文件中的编程命名：
- 方法 / 函数名
- 参数名
- 变量名
- 类型名 / 别名
对照术语表: 将每一个命名与术语表中的规则和定义进行比较。尤其要注意：
- 动词错用: 函数名是否在应该使用
```
search
```
  的地方误用了
```
find
```
  ？
- 名词不一致: 一个代表文件多行内容的
```
string[]
```
  是否被命名为
```
lines
```
  而不是术语表中定义的
```
Content
```
  ？
- 模糊性/歧义: 是否存在像
```
data
```
  ,
```
item
```
  ,
```
val
```
  ,
```
str
```
  这样的模糊命名？在这些地方，是否可以使用术语表中更精确的术语？
汇总偏差: 为当前文件创建一个清单，列出所有已识别的命名偏差。对于每一项偏差，记录其位置（例如，方法名、参数名）、问题描述，以及根据术语表得出的明确修改建议。
重复: 对范围内的所有文件重复此过程。
提交报告: 分析完成后，以清晰、结构化的格式（例如，按文件分组的列表）向用户呈现汇总后的偏差与建议清单。

This is the core execution phase. Systematically analyze each file within the defined scope.

Read files: Read the content of one file at a time.
Analyze naming: Carefully examine the programming names in the file:
- Method / function names
- Parameter names
- Variable names
- Type names / aliases
Cross-reference with the glossary: Compare each name against the rules and definitions in the glossary. Pay particular attention to:
- Incorrect verb usage: Has
```
find
```
  been misused instead of
```
search
```
  in a function name where
```
search
```
  should be used?
- Inconsistent nouns: Is a
```
string[]
```
  representing multiple lines of file content named
```
lines
```
  instead of
```
Content
```
  as defined in the glossary?
- Vagueness/ambiguity: Are there vague names like
```
data
```
  ,
```
item
```
  ,
```
val
```
  ,
```
str
```
  ? In these cases, can more precise terms from the glossary be used?
Summarize deviations: Create a checklist for the current file listing all identified naming deviations. For each deviation, record its location (e.g., method name, parameter name), a description of the issue, and a clear modification suggestion based on the glossary.
Repeat: Repeat this process for all files within the scope.
Submit the report: After analysis is complete, present the summarized list of deviations and suggestions to the user in a clear, structured format (e.g., a list grouped by file).

第四步：实施重构 (Refactor - 可选)

Step 4: Implement Refactoring (Optional)

在提交报告后，Agent 可以主动提出应用这些修改建议。

提议重构: 询问用户：“您希望我将这些命名修正应用到代码库中吗？”
应用修改: 如果用户同意，使用
```
replace
```
工具系统地应用每一个修改建议。为确保准确性，应逐一或按小的逻辑批次执行这些变更。
验证: 重构完成后，最好能运行项目的测试套件，以确保这些变更没有引入任何回归问题。

After submitting the report, the Agent can proactively offer to apply these modification suggestions.

Propose refactoring: Ask the user: "Would you like me to apply these naming corrections to the codebase?"
Apply modifications: If the user agrees, use the
```
replace
```
tool to systematically apply each modification suggestion. To ensure accuracy, execute these changes one by one or in small logical batches.
Verify: After refactoring is complete, it is best to run the project's test suite to ensure these changes do not introduce any regression issues.