Auto Prompt Enhancer for Claude Code

An automated prompt enhancement tool that adds task constraints, workflow standards, and quality gates to Claude Code.

核心特性

特性	说明
speckit 工作流强制	自动执行 specify → plan → tasks → implement 工作流
安全约束	危险操作警告、密钥安全、范围偏移防止
TDD 支持	遇到问题时优先使用测试驱动开发
迭代优化	梯度下降式迭代，动态调整优化次数
Agent 推荐	根据任务类型推荐合适的专业 Agent
双层协同	Hook 强制约束 + 规则指导，确保可靠执行

工作原理

为什么需要 Hook？

用户输入 → Hook 拦截 → 强制追加约束 → 模型执行

方案	优势	劣势	适用场景
Hook 增强	✅ 强制生效，无法绕过 ✅ 无需修改规则文件 ✅ 实时生效	❌ Claude Code 专用 ❌ 依赖 hook 配置	需要强制约束所有输入
纯规则	✅ 可继承复用 ✅ 灵活配置	❌ 可被用户指令覆盖 ❌ 无法强制执行	需要指导建议而非强制

核心原因：Hook 在用户输入后、模型处理前插入，强制约束无法绕过，而规则可能被用户指令覆盖。

双层协同架构

┌─────────────────────────────────────────────────────────────┐
│  Layer 1: Hook 强制约束（不可绕过）                         │
│  文件: auto-prompt-enhancer.py                              │
│  约束:                                                      │
│    - 必须先调研后行动                                        │
│    - 必须 speckit 工作流                                    │
│    - 危险操作必须确认                                       │
│    - 禁止无备份修改核心文件                                  │
└─────────────────────────────────────────────────────────────┘
                              ↓ 协同
┌─────────────────────────────────────────────────────────────┐
│  Layer 2: 规则指导（可被覆盖）                              │
│  文件: auto-prompt-enhancer.json (default-rules.json)       │
│  指导:                                                      │
│    - 编码风格规范                                           │
│    - 测试覆盖率要求                                         │
│    - 安全检查清单                                           │
│    - 调试流程指导                                           │
└─────────────────────────────────────────────────────────────┘

禁止项清单（Hook 强制约束）

类别	禁止项	说明
执行顺序	禁止跳跃步骤	禁止跳过调研/计划直接执行
执行顺序	禁止不经辩驳	严禁不经自我辩驳直接采纳第一个方案
执行顺序	禁止无据推测	禁止用推测代替调研，禁止未验证就下结论
执行顺序	禁止盲目行动	禁止不整理思路就动手
意图对齐	禁止狂妄偏移	禁止偏离用户原始需求自行做决定
意图对齐	禁止范围偏移	只做用户明确要求的，禁止顺手修改无关文件
意图对齐	禁止半成品交付	禁止能跑就行心态，必须完成全部测试
数据安全	禁止恶意投毒	严禁粗狂使用 git 恢复，必须针对性恢复特定部分
数据安全	禁止无备份修改	严禁无 Git 备份修改核心文件
流程规范	禁止无超时操作	严禁所有 Bash/Agent 调用不设 timeout
流程规范	禁止计划未确认	严禁计划未确认前开始执行
流程规范	禁止中断等待	严禁执行中停下等待确认，有计划应持续执行
流程规范	禁止忽略反馈	用户指出问题时必须立即停止并纠正
质量保障	禁止重复造轮子	必须先检查项目已有工具/函数/组件
质量保障	禁止不调研就修改	任何修改文件行为前必须调研（≥30%时间）

项目结构

auto-prompt-enhancer-claude/
├── README.md                    # 本文件
├── LICENSE                     # MIT 许可证
├── auto-prompt-enhancer.py     # 核心脚本（必须）
├── hooks.json                  # Claude Code Hook 配置（必须）
├── default-rules.json          # 默认规则配置（必须）
├── install.sh                  # 安装脚本
├── AI-INSTALL.md               # AI 自动安装指南
├── docs/
│   └── IMPLEMENTATION.md       # 实现原理文档
└── examples/                   # 规则配置示例
    ├── rules-example-zh.json   # 中文规则示例（16条约束）
    ├── rules-example-en.json   # 英文规则示例（16条约束）
    └── RULES-GUIDE.md          # 规则编写指南

安装指南

方式一：自动安装（推荐）

git clone https://github.com/napoler/auto-prompt-enhancer-claude.git
cd auto-prompt-enhancer-claude
chmod +x install.sh
./install.sh

方式二：AI 自动安装

适用于 AI 大模型直接执行安装：

mkdir -p ~/.claude/hooks && \
curl -fsSL https://raw.githubusercontent.com/napoler/auto-prompt-enhancer-claude-code/main/auto-prompt-enhancer.py -o ~/.claude/hooks/auto-prompt-enhancer.py && \
curl -fsSL https://raw.githubusercontent.com/napoler/auto-prompt-enhancer-claude-code/main/default-rules.json -o ~/.claude/hooks/auto-prompt-enhancer.json && \
curl -fsSL https://raw.githubusercontent.com/napoler/auto-prompt-enhancer-claude-code/main/hooks.json -o ~/.claude/hooks/hooks.json && \
echo '{"params": {"text": "test"}}' | python3 ~/.claude/hooks/auto-prompt-enhancer.py > /dev/null 2>&1 && \
echo "✅ 安装成功！重启 Claude Code 即可使用"

方式三：手动安装

# 1. 创建目录（如不存在）
mkdir -p ~/.claude/hooks

# 2. 复制核心文件
cp auto-prompt-enhancer.py ~/.claude/hooks/
cp default-rules.json ~/.claude/hooks/auto-prompt-enhancer.json

# 3. 配置 hooks.json（必须手动添加，不能覆盖！）
# 编辑 ~/.claude/hooks/hooks.json，在 UserPromptSubmit 节点添加：

⚠️ 重要：hooks.json 必须手动配置，不能直接复制覆盖！

在 ~/.claude/hooks/hooks.json 中的 UserPromptSubmit 节点添加：

{
  "matcher": "*",
  "hooks": [
    {
      "type": "command",
      "command": "timeout 5 python3 \"${CLAUDE_HOOKS_DIR}/auto-prompt-enhancer.py\"",
      "timeout": 5
    }
  ],
  "description": "Auto-enhance user prompts with speckit workflow constraints"
}

4. 验证安装

echo '{"params": {"text": "test"}}' | python3 ~/.claude/hooks/auto-prompt-enhancer.py

配置说明

hooks.json 配置

位置: ~/.claude/hooks/hooks.json

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "timeout 5 python3 \"${CLAUDE_HOOKS_DIR}/auto-prompt-enhancer.py\"",
            "timeout": 5
          }
        ],
        "description": "Auto-enhance user prompts with speckit workflow constraints"
      }
    ]
  }
}

⚠️ 注意: matcher: "*" 表示匹配所有输入。command 中的 timeout 5 表示脚本最多执行 5 秒。

auto-prompt-enhancer.json 配置

位置: ~/.claude/hooks/auto-prompt-enhancer.json

完整配置结构

{
  "description": "配置描述",
  "version": "1.0",
  "default_add": false,
  "prefix": "前置追加文本\n",
  "suffix": "后置追加文本\n",
  "rules": [
    {
      "name": "规则名称",
      "match_on": ["关键词1", "关键词2", "*"],
      "prefix": "",
      "suffix": "",
      "template": "匹配时追加的约束文本\n"
    }
  ]
}

字段说明

字段	类型	必需	说明
`description`	string	否	配置描述
`version`	string	否	版本号
`default_add`	boolean	否	默认是否追加所有规则（默认 false）
`prefix`	string	否	所有规则前置追加的文本
`suffix`	string	否	所有规则后置追加的文本
`rules`	array	是	规则数组
`rules[].name`	string	是	规则唯一名称
`rules[].match_on`	array	是	匹配关键词，`"*"` 表示匹配所有
`rules[].prefix`	string	否	此规则前置追加
`rules[].suffix`	string	否	此规则后置追加
`rules[].template`	string	否	匹配时追加的模板文本

match_on 匹配模式

// 匹配所有输入
"match_on": ["*"]

// 包含任一关键词即匹配
"match_on": ["开发", "实现", "修复"]

// 支持正则表达式
"match_on": ["^git ", "git push", "git commit"]

完整示例

{
  "description": "我的自定义规则",
  "version": "1.0",
  "prefix": "【通用约束】\n",
  "rules": [
    {
      "name": "中文优先",
      "match_on": ["*"],
      "template": "【中文】全程使用中文沟通\n"
    },
    {
      "name": "开发任务",
      "match_on": ["开发", "实现", "创建"],
      "template": "【开发】必须使用 speckit 工作流：specify → plan → tasks → implement\n"
    },
    {
      "name": "调试任务",
      "match_on": ["调试", "bug", "报错"],
      "template": "【调试】复现 → 定位根因 → 最小改动修复 → 验证\n"
    }
  ]
}

使用方法

测试脚本

# 在 hooks 目录测试
cd ~/.claude/hooks
echo '{"params": {"text": "帮我开发一个计算器"}}' | python3 auto-prompt-enhancer.py

在 Claude Code 中使用

直接在 Claude Code 输入任务即可：

帮我开发一个计算器

执行流程：

1. Hook 拦截用户输入
         ↓
2. 自动追加约束（speckit 工作流、TODO 记录等）
         ↓
3. 模型执行，模型会：
   - 首先创建 TodoWrite 记录任务
   - 使用 speckit 工作流进行分析
   - 自动进行头脑风暴分析
   - 按计划执行并验证

规则配置示例

示例规则文件说明

文件	触发场景	包含规则
`examples/rules-example-zh.json`	中文环境	16 条中文规则：中文优先、speckit 开发、调试任务、危险操作、TDD 优先等
`examples/rules-example-en.json`	English Environment	16 English rules: language priority, speckit workflow, debug tasks, dangerous ops, TDD first
`examples/RULES-GUIDE.md`	规则编写指南	match_on 匹配逻辑、设计思路、完整示例

示例规则文件列表

实际提供的示例规则文件：

文件	说明
`rules-example-zh.json`	中文环境完整规则集（16条约束）
`rules-example-en.json`	英文环境完整规则集（16条约束）

使用示例规则

查看 examples/ 目录下的规则文件
选择需要的语言版本（中文或英文）
将规则合并到 ~/.claude/hooks/auto-prompt-enhancer.json
重启 Claude Code

快速体验（安装后即可使用）

安装完成后，复制 examples/rules-example-zh.json 或 examples/rules-example-en.json 到 ~/.claude/hooks/auto-prompt-enhancer.json 即可体验完整的规则匹配功能。

卸载指南

# 删除核心文件
rm ~/.claude/hooks/auto-prompt-enhancer.py
rm ~/.claude/hooks/auto-prompt-enhancer.json

# 手动删除 hooks.json 中的配置
# 编辑 ~/.claude/hooks/hooks.json
# 删除 UserPromptSubmit 中的 hook 配置

常见问题

Q: Hook 没有生效？

检查 ~/.claude/hooks/hooks.json 配置是否正确
确认 ${CLAUDE_HOOKS_DIR} 环境变量存在
测试脚本是否可执行：

python3 ~/.claude/hooks/auto-prompt-enhancer.py

Q: 如何添加自定义规则？

编辑 ~/.claude/hooks/auto-prompt-enhancer.json，在 rules 数组中添加新规则：

{
  "name": "my_custom_rule",
  "match_on": ["自定义关键词"],
  "template": "\n\n【自定义规则】...\n"
}

Q: 如何临时禁用增强？

删除或重命名 hooks.json 中的 hook 配置，或设置 default_add: true 并清空规则。

许可证

MIT License - 可自由使用、修改和分发。

贡献

欢迎提交 Issues 和 Pull Requests！

Name		Name	Last commit message	Last commit date
docs		docs
examples		examples
.gitignore		.gitignore
AI-INSTALL-en.md		AI-INSTALL-en.md
AI-INSTALL.md		AI-INSTALL.md
LICENSE		LICENSE
PROJECT_OVERVIEW-en.md		PROJECT_OVERVIEW-en.md
PROJECT_OVERVIEW.md		PROJECT_OVERVIEW.md
README-en.md		README-en.md
README.md		README.md
auto-prompt-enhancer.py		auto-prompt-enhancer.py
default-rules.json		default-rules.json
hooks.json		hooks.json
install.sh		install.sh

Latest commit

History

Folders and files

Repository files navigation