code-naming-auditor

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

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

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

工作流 (Workflow)

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

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

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

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

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

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

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

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

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

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

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

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

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