ECC Swift 钩子规则实战:用 SwiftFormat、SwiftLint 与 swift build 构建 Claude Code 自动化代码质量门禁
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 工作流中的设计思路。