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

ECC Swift 钩子规则实战用 SwiftFormat、SwiftLint 与 swift build 构建 Claude Code 自动化代码质量门禁【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC本文基于 ECCEverything 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.mdrules/ ├── 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 $fileSwiftLint静态风格检查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,cdc);process.stdin.on(end,(){const iJSON.parse(d);const pi.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,cdc);process.stdin.on(end,(){const iJSON.parse(d);const pi.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 中给出了完整的输入 Schemainterface 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.logPython 钩子规则则警告print()并要求改用logging模块。在 Swift 项目中对应的钩子实现可以这样写{ matcher: Edit|Write, hooks: [ { type: command, command: node -e \let d;process.stdin.on(data,cdc);process.stdin.on(end,(){const iJSON.parse(d);const nsi.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_ENABLEDtrue # minimal | standard | strict默认 standard export ECC_HOOK_PROFILEstrict # 按 ID 禁用特定钩子逗号分隔 export ECC_DISABLED_HOOKSpost: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 工作流中的设计思路。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考