ECC Swift 鉤子規(guī)則實戰(zhàn)用 SwiftFormat、SwiftLint 與 swift build 構(gòu)建 Claude Code 自動化代碼質(zhì)量門禁【免費下載鏈接】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規(guī)則體系中面向 Swift 的鉤子規(guī)則文檔 docs/ja-JP/rules/swift/hooks.md系統(tǒng)講解如何借助 Claude Code 的 PostToolUse 鉤子在每次編輯.swift文件后自動執(zhí)行 SwiftFormat 格式化、SwiftLint 靜態(tài)檢查與swift build類型檢查并落地print()調(diào)試語句的攔截與os.Logger/結(jié)構(gòu)化日志遷移。讀完本文你將能夠在 ECC 規(guī)則框架內(nèi)為任意 Swift 項目配置一套編輯即檢查的自動化質(zhì)量門禁并理解其底層鉤子運行機制。Swift 鉤子規(guī)則在 ECC 中的定位ECC 將規(guī)則組織為common 通用層 語言特定層的兩級結(jié)構(gòu)見 rules/README.mdrules/ ├── common/ # 語言無關(guān)的通用原則始終安裝 └── swift/ # Swift 特定內(nèi)容擴展 common 規(guī)則其中 rules/swift/hooks.md以及其日文版 docs/ja-JP/rules/swift/hooks.md在文件頭通過 YAML frontmatter 聲明其生效范圍--- paths: - **/*.swift - **/Package.swift ---這意味著該規(guī)則僅在編輯 Swift 源文件或 SwiftPM 包清單文件時被觸發(fā)與參考。同時文檔開頭明確標注此文件以 Swift 特定內(nèi)容擴展 rules/common/hooks.md——即 Swift 鉤子規(guī)則不是孤立存在的而是對通用鉤子架構(gòu)的 Swift 落地。根據(jù) rules/README.md 的優(yōu)先級約定語言特定規(guī)則在與其通用規(guī)則沖突時優(yōu)先于通用規(guī)則生效。PostToolUse 鉤子三件套格式化、Lint、類型檢查Swift 鉤子規(guī)則的核心是三個 PostToolUse 鉤子全部配置在~/.claude/settings.json中作用時機均為工具執(zhí)行完成后鉤子作用觸發(fā)時機SwiftFormat編輯后自動格式化.swift文件編輯工具完成后SwiftLint編輯后對.swift文件執(zhí)行 Lint 檢查編輯工具完成后swift build對修改過的 Package 做類型檢查編輯工具完成后三個鉤子構(gòu)成一條格式統(tǒng)一 → 風(fēng)格校驗 → 編譯驗證的遞進流水線先由 SwiftFormat 抹平格式差異再由 SwiftLint 按規(guī)則集審計代碼風(fēng)格最后通過swift build確保修改沒有引入編譯期錯誤。SwiftFormat自動格式化SwiftFormat 是社區(qū)廣泛使用的 Swift 代碼格式化工具。配套的編碼風(fēng)格規(guī)則 rules/swift/coding-style.md 還補充了一個重要事實Xcode 16 已內(nèi)置swift-format命令可作為 SwiftFormat 的官方替代方案。在無法安裝第三方工具的環(huán)境下可以直接在鉤子命令中使用swift-format例如swift-format format --in-place $fileSwiftLint靜態(tài)風(fēng)格檢查SwiftLint 負責(zé)執(zhí)行編碼風(fēng)格與靜態(tài)檢查其檢查結(jié)果直接呼應(yīng) rules/swift/coding-style.md 中的 Swift 風(fēng)格約定如優(yōu)先let而非var、默認使用值語義的struct、遵循 Apple API Design Guidelines 命名。Lint 鉤子通常以警告形式輸出不阻塞編輯流程但會強制 Agent 在提交前修復(fù)風(fēng)格問題。swift build類型檢查修改過的包swift build該命令對當(dāng)前 SwiftPM 包執(zhí)行增量編譯與類型檢查確保 Agent 的編輯不會破壞包的整體可編譯性。由于每次編輯后都可能觸發(fā)它依賴 SwiftPM 的增量構(gòu)建能力通常只重建受影響的目標。在 settings.json 中落地配置參照 ECC 鉤子運行時詳見 hooks/README.md的鉤子結(jié)構(gòu)與 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 } ] } ] } }關(guān)鍵配置要點matcher 限定范圍Edit|Write或按需收緊為Edit避免無關(guān)工具觸發(fā)結(jié)合規(guī)則文件頭的paths聲明可進一步把鉤子限制在 Swift 相關(guān)路徑。條件過濾鉤子腳本內(nèi)部用/\.swift$/正則校驗file_path僅對 Swift 文件生效這對應(yīng)了規(guī)則中**/*.swift與**/Package.swift的匹配語義。stdin/stdout 協(xié)議鉤子從 stdin 讀取 JSON 輸入并必須把原始數(shù)據(jù)寫回 stdout詳見 hooks/README.md 的編寫自己的鉤子一節(jié)。鉤子輸入?yún)f(xié)議與退出碼語義要讓上述配置真正可運行、可調(diào)試需要理解 Claude Code 鉤子的底層協(xié)議。ECC 在 hooks/README.md 中給出了完整的輸入 Schemainterface HookInput { tool_name: string; // Bash, Edit, Write, Read 等 tool_input: { command?: string; // Bash: 正在執(zhí)行的命令 file_path?: string; // Edit/Write/Read: 目標文件 old_string?: string; // Edit: 被替換的文本 new_string?: string; // Edit: 替換后的文本 content?: string; // Write: 文件內(nèi)容 }; tool_output?: { // 僅 PostToolUse 可用 output?: string; // 命令/工具輸出 }; }退出碼語義0— 成功繼續(xù)執(zhí)行2— 阻止工具調(diào)用僅 PreToolUse 生效其他非零 — 出錯記錄日志但不阻斷。Swift 鉤子規(guī)則中的三個 PostToolUse 鉤子都屬于執(zhí)行后校驗型它們可以分析結(jié)果、輸出警告但不能阻止編輯——這正是 PostToolUse 與 PreToolUse 的本質(zhì)區(qū)別。若需要硬性阻止應(yīng)使用 PreToolUse 鉤子見 rules/common/hooks.md 對 PreToolUse/PostToolUse/Stop 三類鉤子的定義。警告攔截 print()改用 os.Logger 或結(jié)構(gòu)化日志Swift 鉤子規(guī)則中除 PostToolUse 三件套外的另一項強制約定是對print()語句標記警告——生產(chǎn)代碼中應(yīng)改用os.Logger或結(jié)構(gòu)化日志。這與 ECC 鉤子體系中針對其他語言的同類攔截一脈相承例如 hooks/hooks.json 中的stop:check-console-log鉤子在 Stop 階段檢查所有被修改文件中的console.logPython 鉤子規(guī)則則警告print()并要求改用logging模塊。在 Swift 項目中對應(yīng)的鉤子實現(xiàn)可以這樣寫{ 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() —— 生產(chǎn)代碼請改用 os.Logger 或結(jié)構(gòu)化日志)}console.log(d)})\, description: Warn about print() statements in edited Swift files } ] }推薦的生產(chǎn)級替代方案import os let logger Logger(subsystem: com.example.app, category: network) logger.info(請求完成耗時 \(elapsed)ms) // 結(jié)構(gòu)化日志攜帶 metadata便于采集與檢索 logger.error(請求失敗, metadata: [status: \(statusCode), path: path])相比print()os.Logger具備統(tǒng)一的日志分級debug/info/notice/error/fault、低開銷、系統(tǒng)日志統(tǒng)一采集等能力是生產(chǎn)環(huán)境的正確選擇。鉤子運行機制與源碼佐證上述 Swift 鉤子并非孤立的設(shè)想ECC 倉庫本身就運行著一套完整的鉤子系統(tǒng)。以 hooks/hooks.json 為證倉庫實際注冊了PreToolUse、PreCompact、SessionStart、PostToolUse、PostToolUseFailure、Stop、SessionEnd多個生命周期事件其中PostToolUse通過posttooluse-dispatcher.js分發(fā)器以同步sync超時 30s與異步async超時 45s兩種模式執(zhí)行鉤子其描述明確指出在一個進程中運行同步 PostToolUse 鉤子同時保留每個鉤子的獨立控制。這意味著同步鉤子適合 SwiftFormat/SwiftLint 這類必須立即反映到文件狀態(tài)的格式化任務(wù)異步鉤子適合swift build這類耗時較長、可以后臺完成的類型檢查任務(wù)可聲明async: true與timeout字段詳見 hooks/README.md。此外鉤子支持通過環(huán)境變量做運行時控制無需修改配置文件即可按需啟停# 總開關(guān) 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結(jié)構(gòu)合法。安裝與啟用 Swift 規(guī)則集要使用 Swift 鉤子規(guī)則首先需要安裝 Swift 規(guī)則集。根據(jù) rules/README.md推薦通過安裝腳本安裝./install.sh swift也可以同時安裝多個語言規(guī)則集./install.sh typescript python swift手動安裝時需特別注意必須整目錄復(fù)制不能用/*展開否則會因同名文件覆蓋破壞../common/相對引用mkdir -p ~/.claude/rules/ecc cp -r rules/common ~/.claude/rules/ecc/ cp -r rules/swift ~/.claude/rules/ecc/項目級規(guī)則可同樣放入項目根目錄的.claude/rules/ecc/命名空間下。若需啟用 ECC 自帶的鉤子運行時則使用 hooks/README.md 提供的安裝命令bash ./install.sh --target claude --modules hooks-runtime --enable-hooks安裝完成后將本文前述的 PostToolUse 配置合并進~/.claude/settings.json即可讓 Agent 在每次編輯 Swift 文件后自動執(zhí)行格式化、Lint 與類型檢查。與 Swift 測試、編碼風(fēng)格規(guī)則的聯(lián)動Swift 鉤子規(guī)則是整個 Swift 規(guī)則族rules/swift/ 目錄的一環(huán)與其余規(guī)則協(xié)同構(gòu)成閉環(huán)編碼風(fēng)格rules/swift/coding-style.md 定義了 SwiftFormat/SwiftLint 背后的風(fēng)格基線let優(yōu)先、struct值語義、Apple API 命名規(guī)范、Swift 6 typed throws 與嚴格并發(fā)檢查鉤子負責(zé)把風(fēng)格基線強制落地。測試rules/swift/testing.md 推薦使用 Swift Testing 框架Test/#expect并給出覆蓋率命令swift test --enable-code-coverage通用鉤子架構(gòu)rules/common/hooks.md 定義了 PreToolUse/PostToolUse/Stop 三類鉤子的職責(zé)邊界、TodoWrite 實踐與權(quán)限自動接受的安全注意項Swift 鉤子規(guī)則正是在此架構(gòu)上補充了 Swift 工具鏈的落地細節(jié)。因此一條完整的 Swift 開發(fā)質(zhì)量鏈路是Agent 編輯.swift文件 → PostToolUse 鉤子自動格式化SwiftFormat→ Lint 檢查SwiftLint→ 類型檢查swift build→ print() 攔截提醒os.Logger 遷移→ Stop 階段匯總校驗 → swift test 驗證行為正確性。這正體現(xiàn)了 ECC 以編輯即校驗方式把代碼質(zhì)量門禁前置到 Agent 工作流中的設(shè)計思路。【免費下載鏈接】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創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考