code-naming-auditor

Code Naming Auditor Skill

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

While using this Skill, the Agent's output should avoid Markdown Table format. Using an unformatted text list is sufficient.

Workflow

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

Step 1: Establish the Glossary

A clear and explicit glossary is the foundation of all code audit work.

1. Check for an existing glossary: First, search the project for an existing terminology document. In docs/ or the root directory, look for a file named glossary.md、terminology.md or similar.
2. Confirm with the user: If a document is found, show it to the user and confirm whether it is the "source of truth" for this audit work.
3. 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 (Nouns) (for example Content, Section, Line) and verbs (Verbs) (for example get, find, search, list). When defining the glossary, consider using precise and sufficiently specific names; avoid vague or ambiguous terms.

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

Step 2: Define the Audit Scope

1. Ask the user: Prompt the user to specify the directory or files they want audited.
2. Confirm the scope: Before continuing, confirm the scope with the user. For example: "I will audit src/basics/ all files under the directory. Is that correct?"

Step 3: Analyze and Report

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

1. Read the file: Read the contents of one file at a time.
2. Analyze naming: Carefully inspect the programming names in the file:
   • Method / function names
   • Parameter names
   • Variable names
   • Type names / aliases
3. Compare against the glossary: Compare each name against the rules and definitions in the glossary. Pay particular attention to:
   • Verb misuse: Does a function name mistakenly use search where it should use find？
   • Noun inconsistency: Is a string[] representing multiple lines of content in a file named lines instead of the Content？
   • Ambiguity/vagueness: Are there vague names like data, item, val, str ? In these places, could a more precise term from the glossary be used?
4. Summarize deviations: Create a manifest 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.
5. Repeat: Repeat this process for all files in scope.
6. Submit Report: After the analysis is complete, present the aggregated list of deviations and suggestions to the user in a clear, structured format (e.g., a list grouped by file).

Step 4: Implement Refactoring (Refactor - Optional)

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

1. Propose Refactoring: Ask the user: "Would you like me to apply these naming corrections to the codebase?"
2. Apply Modifications: If the user agrees, use replace tools to systematically apply each modification suggestion. To ensure accuracy, these changes should be executed one by one or in small logical batches.
3. Verify: After refactoring is complete, it is best to run the project's test suite to ensure that these changes have not introduced any regressions.