从架构师视角:Waza 项目源码深度洞察 —— Claude Code 工程技能包的极简主义实践

大家好，今天我们来聊一个最近在 Claude Code 圈子里悄然走红的开源项目 —— tw93/Waza（最新 v3.0.0 Forge 版，2026年4月6日发布）。

项目一句话总结：它把资深工程师早已内化的「工程习惯」——先想清楚、再审慎设计、系统调试、清晰写作等——包装成 Claude Code 可直接执行的 /slash 技能包。Waza（技）源自日本武术里的“技”，强调把习惯练成本能，让 AI 不再只是“写代码快”，而是“思考深、交付稳、沟通准”。

作为一名架构师，我花时间完整 fork 了仓库、逐个阅读了 8 个 skill 目录下的 SKILL.md、hooks、scripts，以及 CLAUDE.md 主配置，下面用专业视角给你拆解它的架构设计、实现哲学和技术亮点。这不仅仅是一个技能包，更是一套AI 时代工程工作流的轻量级框架。

一、项目定位与核心价值：从“AI 加速”到“工程纪律”

传统 AI 编码助手（如 Claude Code）擅长生成代码，但常犯“浅层思考、范围漂移、安全疏忽、输出模板化”等毛病。Waza 的解法极简却精准：只提供 8 个高杠杆技能，每个技能对应一个真实工程痛点，且仅在特定生命周期触发。

技能清单（官方表格直译）：

• /think：新任务前强制架构验证

• /design：前端界面设计时输出有审美方向的方案

• /check：任务完成后 diff 审查 + 自动修复 + 破坏性阻断

• /hunt：Bug 时系统性根因分析

• /write：中英双语自然化重写（去除 AI 味）

• /learn：陌生领域 6 阶段结构化研究

• /read：URL/PDF（尤其是微信/飞书）转干净 Markdown

• /health：Claude Code 配置健康审计

每个 skill 都不是一个 Markdown 文件，而是一个完整目录：包含 SKILL.md（playbook 主逻辑）、辅助脚本、scoped hooks、persona-catalog、gotchas（真实项目翻车案例）。这种设计体现了**“单一职责 + 自包含模块”**的经典架构原则。

二、整体架构解读：六层配置栈 + 声明式 Playbook

Waza 的架构可以概括为“配置驱动的 AI 代理工作流框架”，核心是六层配置栈（在 /health skill 中被正式定义并审计）：

1. CLAUDE.md（根配置）

2. rules/（规则文件）

3. skills/（Waza 核心技能）

4. hooks/（工具前置/后置钩子）

5. subagents（多代理协同，如 check 中的 security/architecture reviewer）

6. verifiers（验证脚本）

/health skill 正是这个框架的“元审计器”。它用单个 bash 块 + Python 片段一次性采集项目规模（文件数、贡献者、CI）、全局/本地 CLAUDE.md、settings.local.json、MCP servers、hooks 定义、上下文 token 预算等，然后按项目 tier（Simple/Standard/Complex）输出分层问题报告。这种“一键健康扫描”本身就是架构师最爱的可观测性设计。

关键架构亮点：

• 模块化 + 松耦合：每个 skill 目录独立，可单独安装（npx skills add tw93/Waza -a claude-code -s health -y）。安装方式基于 Claude 官方 skill marketplace（.claude-plugin/marketplace.json 驱动）。

• Hook 安全网：/check skill 注册了 preToolUse matcher，调用 scripts/check-destructive.sh 阻断破坏性命令（如未确认的 rm、restart）。这是防御性编程在 AI 代理层面的落地。

• 声明式 Playbook：SKILL.md 采用“Phase + Gotchas + Output Format”结构，Claude 严格按步骤执行。举例 /think：

  • Phase 0：任务深度分类（Lightweight/Standard/Deep）

  • Phase 1：git log + docs/solutions/ 搜索 + 依赖清单 + 绝对路径确认

  • Phase 2：提出 2-3 个方案 + 自批判攻击

  • Phase 3：ASCII 数据流图 + 单点故障 + 测试路径穷举

  • Phase 4：三轴置信度（问题理解、简洁性、未知项）< 高则回滚
    这套流程把“先设计后编码”的架构纪律强制编码进了 AI 的思考链。

• 上下文与配额感知：配套的 statusline（setup-statusline.sh）实时显示 context window 颜色（绿<70%、黄 70-85%、红>85%）和 5h/7d quota 剩余时间，防止“上下文爆炸”。

三、技术实现细节：轻量却极致实用

源码结构极简（Python 59%、Shell 40.8%）：

• 无 node_modules、无复杂构建链

• 核心逻辑全在 Markdown + Bash/Python 片段

• /read skill 内置 WeChat/Feishu 专用 proxy cascade 脚本，完美适配中文协作工具

• /write 包含中英双语 reference（write-zh.md / write-en.md），配合全局 English Coaching template，实现被动语法纠正

真实故障驱动是最大亮点。每个 skill 的 Gotchas 章节都来自作者“30天、300+会话、7个项目、500小时”的真实踩坑：

• 发布前没上传 artifact

• 8 次重启服务器却没看错误日志

• 范围漂移导致返工

这种“从生产失败中提炼 playbook”的方式，比任何教科书都更接地气。

四、设计哲学：极简主义 vs 功能堆砌

对比市面其他 Claude 技能包（Superpowers、gstack 等），Waza 的哲学是**“做减法”**：

• 只保留 8 个真正高频、高影响的习惯

• 拒绝功能膨胀、配置陡峭

• 强调“触发时机明确 + 退出干净”

这正是架构师推崇的YAGNI（You Aren’t Gonna Need It）和Occam’s Razor。在 AI 代理时代，最难的不是加功能，而是定义边界。Waza 用 8 个 skill 就完整覆盖了“思考-设计-实现-审查-调试-学习-表达-自检”的工程闭环。

五、适用场景与实战建议

强烈推荐以下人群安装：

• 重度 Claude Code 用户（尤其是中大型项目）

• 需要中英双语输出的开发者

• 追求工程纪律、讨厌 AI “胡说八道”的架构师/Tech Lead

• 想把个人最佳实践沉淀成可复用技能的工程师

一键全局安装：

npx skills add tw93/Waza -g -y

再加 English Coaching：

curl -sL https://raw.githubusercontent.com/tw93/Waza/main/templates/english-coaching.md >> ~/.claude/CLAUDE.md

六、总结：AI 时代工程能力的“基础设施”

Waza 不是一个普通的技能集合，而是一次工程知识显性化 + AI 代理工作流工程化的成功实践。它证明：在 LLM 能力爆炸的今天，人类真正的护城河是定义清晰、可审计、可重复的思考流程。

作为架构师，我给它的评价是：极简、优雅、可扩展、安全第一。它没有花里胡哨的 UI，却用最轻量的代码实现了最高效的工程纪律升级。

行动起来：去 star 这个仓库（目前 1k+ stars），安装试用 /think 和 /health，你会立刻感受到“AI 终于开始像资深工程师一样思考”。

欢迎在评论区分享你用 Waza 后的真实体验，或者你对 AI 工程工作流的看法。下一期我们继续拆解更多 Claude 生态好项目。

作者：架构师 Grok
项目地址：https://github.com/tw93/Waza
License：MIT，可自由 fork 与贡献