ECC Swift 钩子规则实战:用 SwiftFormat、SwiftLint 与 swift build 构建 Claude Code 自动化代码质量门禁

原创2026-09-09 19:15:211,744 阅读
文章标签:人工智能AI 技能AI 插件AI 评测提示工程MCP ClientsAgent 记忆开发工具

ECC Swift 钩子规则实战:用 SwiftFormat、SwiftLint 与 swift build 构建 Claude Code 自动化代码质量门禁

本文基于 ECC(Everything Claude Code)规则体系中面向 Swift 的钩子规则文档 docs/ja-JP/rules/swift/hooks.md,系统讲解如何借助 Claude Code 的 PostToolUse 钩子在每次编辑 .swift 文件后自动执行 SwiftFormat 格式化、SwiftLint 静态检查与 swift build 类型检查,并落地 print() 调试语句的拦截与 os.Logger/结构化日志迁移。读完本文,你将能够在 ECC 规则框架内为任意 Swift 项目配置一套"编辑即检查"的自动化质量门禁,并理解其底层钩子运行机制。

Swift 钩子规则在 ECC 中的定位

ECC 将规则组织为 common 通用层 + 语言特定层 的两级结构(见 rules/README.md):

rules/
├── common/    # 语言无关的通用原则(始终安装)
└── swift/     # Swift 特定内容,扩展 common 规则

其中 rules/swift/hooks.md(以及其日文版 docs/ja-JP/rules/swift/hooks.md)在文件头通过 YAML frontmatter 声明其生效范围:

---
paths:
  - "**/*.swift"
  - "**/Package.swift"
---

这意味着该规则仅在编辑 Swift 源文件或 SwiftPM 包清单文件时被触发与参考。同时,文档开头明确标注:"此文件以 Swift 特定内容扩展 rules/common/hooks.md"——即 Swift 钩子规则不是孤立存在的,而是对通用钩子架构的 Swift 落地。根据 rules/README.md 的优先级约定,语言特定规则在与其通用规则冲突时优先于通用规则生效。

PostToolUse 钩子三件套:格式化、Lint、类型检查

Swift 钩子规则的核心是三个 PostToolUse 钩子,全部配置在 ~/.claude/settings.json 中,作用时机均为"工具执行完成后":

钩子 作用 触发时机
SwiftFormat 编辑后自动格式化 .swift 文件 编辑工具完成后
SwiftLint 编辑后对 .swift 文件执行 Lint 检查 编辑工具完成后
swift build 对修改过的 Package 做类型检查 编辑工具完成后

三个钩子构成一条"格式统一 → 风格校验 → 编译验证"的递进流水线:先由 SwiftFormat 抹平格式差异,再由 SwiftLint 按规则集审计代码风格,最后通过 swift build 确保修改没有引入编译期错误。

SwiftFormat:自动格式化

SwiftFormat 是社区广泛使用的 Swift 代码格式化工具。配套的编码风格规则 rules/swift/coding-style.md 还补充了一个重要事实:Xcode 16+ 已内置 swift-format 命令,可作为 SwiftFormat 的官方替代方案。在无法安装第三方工具的环境下,可以直接在钩子命令中使用 swift-format,例如:

swift-format format --in-place "$file"

SwiftLint:静态风格检查

SwiftLint 负责执行编码风格与静态检查,其检查结果直接呼应 rules/swift/coding-style.md 中的 Swift 风格约定(如优先 let 而非 var、默认使用值语义的 struct、遵循 Apple API Design Guidelines 命名)。Lint 钩子通常以警告形式输出,不阻塞编辑流程,但会强制 Agent 在提交前修复风格问题。

swift build:类型检查修改过的包

swift build

该命令对当前 SwiftPM 包执行增量编译与类型检查,确保 Agent 的编辑不会破坏包的整体可编译性。由于每次编辑后都可能触发,它依赖 SwiftPM 的增量构建能力,通常只重建受影响的目标。

在 settings.json 中落地配置

参照 ECC 钩子运行时(详见 hooks/README.md)的钩子结构与 hooks/hooks.json 中的真实写法,一个面向 Swift 的 PostToolUse 配置如下:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const p=i.tool_input?.file_path||'';if(/\\.swift$/.test(p)){const{execFileSync}=require('child_process');try{execFileSync('swiftformat',['--lint','--quiet',p],{stdio:'pipe'})}catch(e){console.error('[SwiftLint] '+p+' 未通过格式检查')}}console.log(d)})\"",
            "description": "SwiftLint: run lint checks after editing .swift files"
          },
          {
            "type": "command",
            "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const p=i.tool_input?.file_path||'';if(/\\.swift$/.test(p)){const{execFileSync}=require('child_process');try{execFileSync('swiftlint',['lint','--quiet',p],{stdio:'pipe'})}catch(e){console.error('[SwiftLint] '+p+' 存在 Lint 问题')}}console.log(d)})\"",
            "description": "SwiftLint: run lint checks after editing .swift files"
          }
        ]
      }
    ]
  }
}

也可以配置为仅格式化模式:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "swiftformat \"$CLAUDE_FILE_PATH\"",
            "description": "SwiftFormat: auto-format .swift files after edit"
          }
        ]
      }
    ]
  }
}

关键配置要点:

  • matcher 限定范围:Edit|Write 或按需收紧为 Edit,避免无关工具触发;结合规则文件头的 paths 声明,可进一步把钩子限制在 Swift 相关路径。
  • 条件过滤:钩子脚本内部用 /\.swift$/ 正则校验 file_path,仅对 Swift 文件生效,这对应了规则中 **/*.swift 与 **/Package.swift 的匹配语义。
  • stdin/stdout 协议:钩子从 stdin 读取 JSON 输入,并必须把原始数据写回 stdout(详见 hooks/README.md 的"编写自己的钩子"一节)。

钩子输入协议与退出码语义

要让上述配置真正可运行、可调试,需要理解 Claude Code 钩子的底层协议。ECC 在 hooks/README.md 中给出了完整的输入 Schema:

interface HookInput {
  tool_name: string;          // "Bash", "Edit", "Write", "Read" 等
  tool_input: {
    command?: string;         // Bash: 正在执行的命令
    file_path?: string;       // Edit/Write/Read: 目标文件
    old_string?: string;      // Edit: 被替换的文本
    new_string?: string;      // Edit: 替换后的文本
    content?: string;         // Write: 文件内容
  };
  tool_output?: {             // 仅 PostToolUse 可用
    output?: string;          // 命令/工具输出
  };
}

退出码语义:

  • 0 — 成功,继续执行;
  • 2 — 阻止工具调用(仅 PreToolUse 生效);
  • 其他非零 — 出错,记录日志但不阻断。

Swift 钩子规则中的三个 PostToolUse 钩子都属于"执行后校验"型:它们可以分析结果、输出警告,但不能阻止编辑——这正是 PostToolUse 与 PreToolUse 的本质区别。若需要硬性阻止,应使用 PreToolUse 钩子(见 rules/common/hooks.md 对 PreToolUse/PostToolUse/Stop 三类钩子的定义)。

警告:拦截 print(),改用 os.Logger 或结构化日志

Swift 钩子规则中除 PostToolUse 三件套外的另一项强制约定是:

对 print() 语句标记警告——生产代码中应改用 os.Logger 或结构化日志。

这与 ECC 钩子体系中针对其他语言的同类拦截一脉相承(例如 hooks/hooks.json 中的 stop:check-console-log 钩子在 Stop 阶段检查所有被修改文件中的 console.log,Python 钩子规则则警告 print() 并要求改用 logging 模块)。在 Swift 项目中,对应的钩子实现可以这样写:

{
  "matcher": "Edit|Write",
  "hooks": [
    {
      "type": "command",
      "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const ns=i.tool_input?.new_string||'';if(/print\\(/.test(ns)){console.error('[Hook] 检测到 print() —— 生产代码请改用 os.Logger 或结构化日志')}console.log(d)})\"",
      "description": "Warn about print() statements in edited Swift files"
    }
  ]
}

推荐的生产级替代方案:

import os

let logger = Logger(subsystem: "com.example.app", category: "network")
logger.info("请求完成,耗时 \(elapsed)ms")

// 结构化日志:携带 metadata,便于采集与检索
logger.error("请求失败", metadata: ["status": "\(statusCode)", "path": path])

相比 print(),os.Logger 具备统一的日志分级(debug/info/notice/error/fault)、低开销、系统日志统一采集等能力,是生产环境的正确选择。

钩子运行机制与源码佐证

上述 Swift 钩子并非孤立的设想,ECC 仓库本身就运行着一套完整的钩子系统。以 hooks/hooks.json 为证,仓库实际注册了 PreToolUse、PreCompact、SessionStart、PostToolUse、PostToolUseFailure、Stop、SessionEnd 多个生命周期事件;其中 PostToolUse 通过 posttooluse-dispatcher.js 分发器以同步(sync,超时 30s)与异步(async,超时 45s)两种模式执行钩子,其描述明确指出"在一个进程中运行同步 PostToolUse 钩子,同时保留每个钩子的独立控制"。这意味着:

  • 同步钩子适合 SwiftFormat/SwiftLint 这类必须立即反映到文件状态的格式化任务;
  • 异步钩子适合 swift build 这类耗时较长、可以后台完成的类型检查任务(可声明 "async": true 与 "timeout" 字段,详见 hooks/README.md)。

此外,钩子支持通过环境变量做运行时控制,无需修改配置文件即可按需启停:

# 总开关
export ECC_HOOKS_ENABLED=true

# minimal | standard | strict(默认 standard)
export ECC_HOOK_PROFILE=strict

# 按 ID 禁用特定钩子(逗号分隔)
export ECC_DISABLED_HOOKS="post:swift:format,post:swift:lint"

配置文件类钩子还能得到 schemas/hooks.schema.json 的 JSON Schema 校验支持,保证 settings.json 结构合法。

安装与启用 Swift 规则集

要使用 Swift 钩子规则,首先需要安装 Swift 规则集。根据 rules/README.md,推荐通过安装脚本安装:

./install.sh swift

也可以同时安装多个语言规则集:

./install.sh typescript python swift

手动安装时需特别注意:必须整目录复制,不能用 /* 展开,否则会因同名文件覆盖破坏 ../common/ 相对引用:

mkdir -p ~/.claude/rules/ecc
cp -r rules/common ~/.claude/rules/ecc/
cp -r rules/swift ~/.claude/rules/ecc/

项目级规则可同样放入项目根目录的 .claude/rules/ecc/ 命名空间下。若需启用 ECC 自带的钩子运行时,则使用 hooks/README.md 提供的安装命令:

bash ./install.sh --target claude --modules hooks-runtime --enable-hooks

安装完成后,将本文前述的 PostToolUse 配置合并进 ~/.claude/settings.json,即可让 Agent 在每次编辑 Swift 文件后自动执行格式化、Lint 与类型检查。

与 Swift 测试、编码风格规则的联动

Swift 钩子规则是整个 Swift 规则族(rules/swift/ 目录)的一环,与其余规则协同构成闭环:

  • 编码风格:rules/swift/coding-style.md 定义了 SwiftFormat/SwiftLint 背后的风格基线(let 优先、struct 值语义、Apple API 命名规范、Swift 6 typed throws 与严格并发检查),钩子负责把风格基线强制落地。
  • 测试:rules/swift/testing.md 推荐使用 Swift Testing 框架(@Test/#expect),并给出覆盖率命令:
swift test --enable-code-coverage
  • 通用钩子架构:rules/common/hooks.md 定义了 PreToolUse/PostToolUse/Stop 三类钩子的职责边界、TodoWrite 实践与权限自动接受的安全注意项,Swift 钩子规则正是在此架构上补充了 Swift 工具链的落地细节。

因此,一条完整的 Swift 开发质量链路是:Agent 编辑 .swift 文件 → PostToolUse 钩子自动格式化(SwiftFormat)→ Lint 检查(SwiftLint)→ 类型检查(swift build)→ print() 拦截提醒(os.Logger 迁移)→ Stop 阶段汇总校验 → swift test 验证行为正确性。这正体现了 ECC 以"编辑即校验"方式把代码质量门禁前置到 Agent 工作流中的设计思路。

登录后查看全文
ECC