code-style-validator

安装

无需单独下载：此技能运行仓库内的工具 .claude/tools/cli/security-lint.cjs。

• 确保已安装 Node.js（v18+）：访问 nodejs.org，或运行 winget install OpenJS.NodeJS.LTS（Windows）、brew install node（macOS）。
• 在项目根目录中，脚本会自动调用；无需额外安装步骤。

速查表与最佳实践

基于 AST 的验证： 使用 ESLint（或同类工具）及选择器／模式；规则会针对特定节点类型进行检查。优先使用现有的社区规则，再编写自定义规则；自定义规则需要包含 meta（type、fixable、schema）和 create。

流程： 检查命名方式（camelCase/PascalCase/snake_case）、缩进、导入顺序、函数／类结构和注释风格。在提交前钩子和 CI 中运行；尽可能提供自动修复功能。

技巧： 对可自动修复的规则使用 --fix；结合 security-lint 执行策略。清晰定义规则元数据，以便用于文档和工具。使用 AST 选择器进行精确的模式匹配（节点类型、属性、子节点／同级节点）。

认证与培训

ESLint： 在项目中使用、自定义规则、选择器。没有认证；技能数据：基于 AST 的验证、提交前钩子／CI、自动修复、命名／缩进／导入。

钩子与工作流

建议的钩子： 提交前：运行 security-lint（技能脚本）或 ESLint；失败时阻止提交。与 developer（辅助）、code-reviewer（辅助）、qa（CI）搭配使用。

工作流： 与 code-reviewer（辅助）、developer（辅助）搭配使用。流程：提交前或在 CI 中 → 运行验证器 → 修复或阻止。参见 code-review-workflow.md、validation 钩子。

代码风格验证器 - 使用 AST（抽象语法树）分析，以编程方式验证代码风格。通过自动检查补充代码风格规则。 - 提交代码前 - 在提交前钩子中 - 代码审查期间 - 在 CI/CD 流水线中 - 强制执行一致的代码风格

步骤 1：识别代码风格模式

分析代码库以识别风格模式：

• 命名约定（camelCase、PascalCase、snake_case）
• 缩进风格（空格或制表符、宽度）
• 导入组织方式
• 函数／类结构
• 注释风格

### 步骤 2：基于 AST 的验证

使用特定语言的 AST 解析器：

TypeScript/JavaScript： </execution_process>

**TypeScript/JavaScript AST 验证**：

const ts = require('typescript');
const fs = require('fs');

function validateTypeScriptFile(filePath) {
  const sourceCode = fs.readFileSync(filePath, 'utf8');
  const sourceFile = ts.createSourceFile(filePath, sourceCode, ts.ScriptTarget.Latest, true);

  const issues = [];

  // Validate naming conventions
  ts.forEachChild(sourceFile, node => {
    if (ts.isFunctionDeclaration(node) && node.name) {
      if (!/^[a-z][a-zA-Z0-9]*$/.test(node.name.text)) {
        issues.push({
          line: sourceFile.getLineAndCharacterOfPosition(node.name.getStart()).line + 1,
          message: `Function name "${node.name.text}" should be camelCase`,
        });
      }
    }
  });

  return issues;
}

</code_example>

<code_example> Python AST 验证：

import ast
import re

def validate_python_file(file_path):
    with open(file_path, 'r') as f:
        source_code = f.read()

    tree = ast.parse(source_code)
    issues = []

    for node in ast.walk(tree):
        if isinstance(node, ast.FunctionDef):
            if not re.match(r'^[a-z][a-z0-9_]*$', node.name):
                issues.append({
                    'line': node.lineno,
                    'message': f'Function name "{node.name}" should be snake_case'
                })

    return issues

</code_example>

<code_example> 样式检查：

命名约定：

• 变量：camelCase（JS/TS）或 snake_case（Python）
• 函数：camelCase（JS/TS）或 snake_case（Python）
• 类：PascalCase
• 常量：UPPER_CASE
• 私有成员：以下划线为前缀

格式：

• 缩进：2 个空格（JS/TS）或 4 个空格（Python）
• 行长：88-100 个字符
• 尾随逗号：使用（JS/TS）
• 分号：保持用法一致

结构：

• 导入顺序：外部、内部、相对路径
• 函数长度：< 50 行
• 文件组织：导出项、辅助函数、类型 </code_example>

<code_example> 使用示例（模板——先实现验证器）：

验证单个文件：

# After implementing your validator:
node validate-code-style.js src/components/Button.tsx

验证目录：

# After implementing your validator:
node validate-code-style.js src/components/

输出格式：

{
  "file": "src/components/Button.tsx",
  "valid": false,
  "issues": [
    {
      "line": 15,
      "column": 10,
      "rule": "naming-convention",
      "message": "Variable 'UserData' should be camelCase: 'userData'",
      "severity": "error"
    },
    {
      "line": 23,
      "column": 5,
      "rule": "indentation",
      "message": "Expected 2 spaces, found 4",
      "severity": "warning"
    }
  ],
  "summary": {
    "total": 2,
    "errors": 1,
    "warnings": 1
  }
}

</code_example>

<code_example> Pre-commit Hook（模板——先实现验证器）：

#!/bin/bash
# .git/hooks/pre-commit
changed_files=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|tsx|js|jsx|py)$')

for file in $changed_files; do
  # Replace with your actual validator path
  if ! node validate-code-style.js "$file"; then
    echo "Code style validation failed for $file"
    exit 1
  fi
done

</code_example>

<code_example> CI/CD 集成（模板——先实现验证器）：

# .github/workflows/code-style.yml
- name: Validate code style
  run: |
    # Replace with your actual validator path
    node validate-code-style.js src/
    if [ $? -ne 0 ]; then
      echo "Code style validation failed"
      exit 1
    fi

</code_example>

1. **互补而非替代**：此工具用于补充代码样式规则，而非替代它们 2. **规则可配置**：允许团队自定义验证规则 3. **尽可能自动修复**：为常见问题提供自动修复建议 4. **快速反馈**：在开发过程中即时提供反馈 5. **清晰的消息**：显示清晰的错误消息，并附上行号和建议

铁律

1. 始终优先使用基于 AST 的验证，而非正则表达式——基于正则表达式的样式检查在处理多行结构、注释和字符串时会出错；基于 AST 的工具（ESLint、Prettier）与格式无关，且在语义上准确。
2. 编写自定义规则前，始终检查是否已有 ESLint/Prettier 规则可用——自定义规则维护成本高；现有规则及其配置已覆盖 95% 的样式需求。
3. 绝不因样式警告阻止提交，只对错误进行阻止——警告仅供参考；因警告阻止 CI 会造成阻碍，导致团队彻底禁用样式检查。
4. 始终在发现问题的同时提供自动修复建议——没有自动修复的报告需要对每个问题进行人工干预；可自动修复的违规项解决率接近 100%，而手动修复仅为 30%。
5. 始终在 pre-commit hook 和 CI 中运行样式验证——pre-commit 能在问题进入代码库前于本地发现问题；CI 则能捕获 hook 被绕过或未安装的情况。

反模式

反模式	失败原因	正确做法
基于正则表达式的样式检查	处理多行内容、字符串和注释时会出错	使用基于 AST 的工具（ESLint、Prettier）
为已有标准编写自定义规则	维护成本高；与社区标准不一致	先配置现有 ESLint/Prettier 规则
因警告阻止 CI	过多阻碍会导致团队禁用样式检查	仅因错误而阻止；记录警告
样式验证不提供自动修复	手动修复的解决率较低	始终在问题旁提供自动修复命令
只在本地运行，不在 CI 中运行	开发者经常绕过 pre-commit hook	在 pre-commit 和 CI 流水线中都运行

Memory Protocol（必须遵守）

开始前： 阅读 .claude/context/memory/learnings.md

完成后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现的问题 -> .claude/context/memory/issues.md
• 做出的决定 -> .claude/context/memory/decisions.md

假设工作会被中断：如果未记录在记忆中，就等于从未发生。