1. 项目概述一个让AI先理解再执行的Claude Code技能如果你用过Claude Code或者任何AI编程助手一定遇到过这种情况你脑子里有个模糊的想法噼里啪啦打了一长串指令过去结果AI要么跑偏了方向要么直接给你一个看似能用、实则漏洞百出的方案。你看着那堆代码心里直犯嘀咕“这玩意儿真的能跑吗” 然后就是来回拉扯、反复修改时间全耗在沟通成本上了。我最近在折腾一个叫promptly-prompt的Claude Code技能它解决的就是这个痛点。这玩意儿不是什么花里胡哨的提示词模板库它的核心思想极其简单粗暴在AI动手干活之前先逼它停下来把活儿想明白、问清楚、找对路。你可以把它理解成一个“AI防呆板”或者“需求澄清器”。它不会帮你写更华丽的提示词而是强制AI在接到复杂任务时先完成三个关键动作明确能力边界、深度理解需求、搜索现有方法。这背后的洞见是大多数糟糕的AI回答根源不在于提示词技巧不够而在于上下文信息缺失和需求理解偏差。这个技能本质上是一个UserPromptSubmit钩子Hook。当你向Claude Code提交一个指令时这个钩子会自动拦截并基于一套规则给指令的“复杂度”打分。如果分数超过阈值它就会在指令真正送达AI模型之前自动注入一段强制性的“思考与确认”流程。简单指令如git status或/commit则会直接放行毫不拖沓。我自己在深度使用几周后最大的感受是它把我和AI的协作从“我说你猜”的模糊博弈变成了“先对齐再开工”的清晰流程效率提升是实实在在的。2. 核心设计思路与原理拆解2.1 从“提示工程”到“上下文工程”的理念转变传统的“提示工程”Prompt Engineering往往聚焦于如何精心雕琢输入给AI的指令比如使用特定的格式、加入思维链Chain-of-Thought提示、或者提供更详细的例子。这当然有效但它本质上是一种“单向优化”即人类需要不断猜测AI的“理解模式”并调整自己的表达。promptly-prompt代表的是一种范式转移我称之为“上下文工程”Context Engineering。它的核心假设是AI输出的质量首要取决于它是否拥有正确、完整且无歧义的上下文而非提示词本身的装饰程度。因此它的设计目标不是优化人类输入的语言而是在AI处理输入之前主动为AI构建一个高质量的决策上下文。这个上下文包含三个维度自我认知上下文让AI明确“针对这个具体任务我能做什么不能做什么我还缺什么信息”。需求澄清上下文让AI与用户对齐“你到底想要什么有哪些没说出来的隐含条件和潜在风险”。方法检索上下文迫使AI在动手前先想想“有没有现成的轮子可以用”避免重复造轮子或使用错误的方法。这种思路非常符合软件工程中的“契约优先”或“设计先行”原则。在写代码前先定义好接口和约束远比写了一半再回头修改要高效得多。2.2 钩子Hook机制与复杂度评分算法这个技能的实现依赖于Claude Code的插件钩子系统。UserPromptSubmit是一个关键钩子它在用户提交的提示词被发送给AI模型进行推理之前触发。promptly-prompt在这里插入了一个Python脚本作为拦截器。这个拦截器的核心是一个基于规则的复杂度评分系统。它不依赖任何外部API或复杂的NLP模型只使用Python标准库对原始提示文本进行快速分析。评分逻辑设计得非常务实旨在捕捉那些容易引发误解的“模糊请求”特征信号特征分值设计逻辑与考量长文本(80英文单词或中文字符)2长文本通常包含复杂需求或多重目标信息密度高容易遗漏关键点。中等文本(40–80单词)1有一定复杂度但可能边界清晰。给予适中权重。多句子(3句)1多个句子可能意味着多个步骤或并列条件需要拆解。多步骤词汇(“then”, “然后”, “接着”, “下一步”)2 (每个上限3)这是最强烈的“复杂流程”信号。每个此类词汇都显著增加任务步骤。模糊性词汇(“maybe”, “大概”, “可能”, “或许”)1 (每个上限3)这类词汇直接指向需求的不确定性是必须澄清的红灯。多个问号(1个?)1多个问题意味着需要多个答案或一个复合答案需要分别处理。包含代码块或文件路径-2这通常是一个具体的、上下文明确的编程任务AI处理起来反而更直接。负分使其更容易被放行。以祈使动词开头(“fix”, “run”, “git”, “写一个”)-1简短、明确的命令式指令目标清晰。斜杠命令(/commit,/explain)-3Claude Code的内置命令格式和目的高度标准化几乎无需解释。超短文本(10字符)-3如lspwd 过于简单直接通过。总分 ≥ 3时触发拦截和上下文注入流程。总分 3时提示词原封不动地传递给AI整个过程对用户无感耗时小于50毫秒。这个评分表的设计体现了实用主义哲学它不去追求完美的语义理解而是用一些简单、可计算的启发式规则快速识别出“高误解风险”的提示。在实际使用中我发现这个规则集覆盖了90%以上的模糊场景。实操心得理解评分阈值阈值“3”是一个经验值。设置太低会打断太多简单操作惹人烦设置太高又会让一些本该被澄清的复杂请求溜过去。你可以通过修改源码中的阈值来调整技能的“敏感度”。比如如果你经常处理非常复杂的分析任务可以将阈值提高到4或5如果你希望AI对任何稍有不确定性的请求都保持谨慎可以降到2。找到适合你工作流的平衡点很重要。2.3 三层强制纪律的深层逻辑当复杂请求被拦截后技能会向对话中注入一段系统指令强制AI执行以下三层纪律。这不是建议而是必须遵循的流程。第一层能力边界声明强制内容“针对这个任务请明确1. 你能直接完成的部分是什么2. 你缺乏哪些关键信息或上下文3. 在这个领域你的知识或方法可能存在哪些局限性或偏见”为什么重要这避免了AI“不懂装懂”或盲目自信。例如你让AI“设计一个推荐系统”它可能会立刻开始写协同过滤的代码。但经过这一层它可能会说“我可以提供算法思路和示例代码但我需要知道你的数据规模百万级还是千万级、业务场景电商还是内容和实时性要求。此外我对最新的一些深度排序模型如DeepFM的实践经验可能基于公开论文缺乏特定行业调参经验。” 这样一来风险前置了。第二层需求深度理解与澄清强制内容“请深入解读我的请求1. 目标受众和使用场景是什么2. 产出物后续如何被使用是原型、生产代码还是报告3. 有哪些我未言明的约束如性能、成本、合规4. 这个任务最可能失败的环节是什么5. 请求中有哪些模糊或歧义之处请列出并等待我确认。”为什么重要这是解决“需求鸿沟”的关键。用户经常以为自己说清楚了但其实遗漏了大量隐含信息。比如“帮我写个爬虫”AI经过这一层会问“爬取的目标网站是否有反爬机制需要遵守的robots.txt规则是什么数据更新频率要求是多少爬取的数据是用于个人分析还是商业用途这涉及法律风险” 这些问题不问清楚写出来的代码很可能无法使用。第三层方法论搜索强制内容“在开始构建之前请先搜索现有的方法论、框架、开源库或已验证的模式。请使用工具进行搜索并给出具体的项目名称、文档链接或模式描述而不是模糊的建议。”为什么重要这是为了对抗AI的“绿色田野综合征”Green Field Syndrome——总倾向于从零开始构建。实际上软件世界99%的问题都有现成的解决方案。强制搜索能节省大量时间并提高方案质量。例如当你说“实现一个实时聊天功能”AI不会直接去写WebSocket代码而是会先搜索并推荐“可以考虑使用成熟的解决方案如Socket.IO库或集成第三方服务如Pusher、Firebase Realtime Database。这是它们的优缺点比较……”这三层纪律本质上是在AI内部模拟了一个优秀工程师接到任务后的思考流程评估可行性 - 澄清需求 - 调研方案。它把隐性的思维过程显性化、结构化并置于用户的监督之下。3. 安装、配置与核心工作流程实操3.1 多种安装方式详解与选择promptly-prompt提供了几种安装方式适用于不同场景的用户。方式一通过Claude插件市场安装推荐给大多数用户这是最简便、最不容易出错的方式适合希望开箱即用的用户。打开你的终端Terminal。依次执行以下两条命令claude plugin marketplace add recomby-ai/promptly-prompt claude plugin install promptly-promptpromptly-prompt第一条命令是将这个技能的仓库地址添加到本地的Claude插件市场中。第二条命令是从该仓库安装特定版本的技能。安装完成后启动或重启你的Claude Code会话即可生效。方式二在Claude Code会话内一键安装如果你已经在一个Claude Code会话中可以更快捷地安装。直接在会话输入框里以!开头执行命令! claude plugin marketplace add recomby-ai/promptly-prompt ! claude plugin install promptly-promptpromptly-prompt注意!是Claude Code中执行系统命令的特殊前缀。这种方式的好处是无需切换窗口。方式三一键脚本安装适合喜欢终端操作的用户如果你习惯用git和bash这是一条命令搞定所有事git clone https://github.com/recomby-ai/promptly-prompt.git cd promptly-prompt bash install.sh这条命令依次执行了克隆代码仓库 - 进入仓库目录 - 运行安装脚本。安装脚本install.sh会自动完成文件复制和配置修改。你需要确保系统已安装git。方式四手动安装适合高级用户或需要自定义的情况如果你想深入了解机制或打算修改源码手动安装是最好的选择。克隆或下载项目文件。创建技能目录并复制文件# 创建技能专属目录 mkdir -p ~/.claude/skills/promptly-prompt/scripts # 复制核心技能定义文件 cp path/to/promptly-prompt/skill/SKILL.md ~/.claude/skills/promptly-prompt/ # 复制核心拦截器Python脚本 cp path/to/promptly-prompt/skill/scripts/intercept.py ~/.claude/skills/promptly-prompt/scripts/请将path/to/promptly-prompt替换为你实际存放项目文件的路径。修改Claude Code配置文件这是最关键的一步。你需要编辑Claude Code的全局设置文件~/.claude/settings.json。如果该文件不存在可以创建它。{ hooks: { UserPromptSubmit: [ { matcher: , // 空字符串表示匹配所有提示 hooks: [ { type: command, command: python3 ~/.claude/skills/promptly-prompt/scripts/intercept.py } ] } ] } }这段配置告诉Claude Code对于所有用户提交的提示matcher: 都先执行指定的Python命令。该脚本会读取原始提示进行评分和判断并将处理后的结果输出到标准输出stdoutClaude Code会捕获这个输出作为新的提示。启动一个新的Claude Code会话。配置文件的修改通常需要重启会话才能加载。注意事项路径与权限在手动安装时command中的Python脚本路径必须是绝对路径。使用~家目录是可行的但如果你不确定可以用pwd命令获取当前目录的绝对路径。确保intercept.py脚本具有可执行权限或者确保你的Python3环境可以正常调用它。通常不需要特殊权限。settings.json是一个JSON文件格式必须严格正确。缺少一个逗号或括号都可能导致Claude Code无法启动。建议使用支持JSON校验的编辑器如VSCode进行编辑。3.2 技能触发与交互全流程实录安装成功后让我们通过一个真实场景来看看它是如何工作的。场景我想让AI帮我优化一个数据库查询。原始模糊请求用户输入“我有个用户表查询很慢帮我优化一下SQL还要考虑以后数据量大了怎么办。”这是一个非常典型的、充满模糊点的日常请求。我们来一步步拆解AI在promptly-prompt作用下的反应。第一步复杂度评分文本长度中等约20字1分。包含多步骤词汇“还要考虑”2分。总计3分。达到触发阈值。第二步AI输出强制纪律流程AI不会直接回答如何优化SQL而是会输出类似以下内容以下是我根据其逻辑模拟的典型回应promptly-prompt介入此请求复杂度较高建议先进行以下澄清1. 能力边界声明我能做什么我可以分析SQL语句的潜在性能瓶颈如缺失索引、全表扫描、嵌套循环并提供重写建议、索引添加方案。我也可以介绍常见的数据库分库分表、读写分离、缓存策略等架构概念。我缺少的信息我无法直接访问你的数据库执行计划EXPLAIN、表结构CREATE TABLE语句、索引情况、数据分布基数以及当前的服务器配置。没有这些我的建议可能是泛泛而谈。潜在局限性我的优化建议基于通用的SQL最佳实践和常见数据库系统如MySQL、PostgreSQL的特性。对于特定数据库的独有优化器特性或非常规的硬件瓶颈我的知识可能不全面。2. 需求深度理解与澄清目标与场景这个优化是为了解决当前线上服务的慢查询报警吗还是开发环境的性能测试目标是将查询时间从多少秒降低到多少秒下游使用优化后的SQL是直接用于生产环境还是作为一个方案供DBA评审未言明约束数据库类型和版本是MySQL 8.0? PostgreSQL 14?是否可以修改表结构添加索引应用代码是否容易修改是否有运维或DBA团队的规范限制预算约束是否可以考虑引入Redis这样的缓存中间件主要失败风险盲目添加索引可能导致写性能下降架构改动如分表需要应用层大量重构。模糊点确认“用户表”的具体表名和主要字段是“查询很慢”的具体SQL语句是什么当前执行时间是多少“数据量大了”的具体指标是多少百万级、千万级还是亿级 请提供上述信息或确认我们可以基于某些假设继续。3. 方法论搜索建议在深入优化前建议先确认是否已有成熟工具或方法数据库内置工具是否已使用EXPLAIN ANALYZE(PostgreSQL) 或EXPLAIN FORMATJSON(MySQL) 查看了执行计划监控系统是否有像Prometheus Grafana, Percona Monitoring and Management (PMM)这样的监控可以定位慢查询开源方案对于“数据量大了”的架构问题是否有现成的中间件方案可以考虑如Vitess用于MySQL分片、CitusPostgreSQL分布式扩展或TiDB请基于以上澄清点提供更多信息或确认我们可以基于某些通用假设例如假设是MySQL 8.0表数据量在千万级进行下一步。第三步用户补充信息AI继续这时我需要回答AI提出的问题。假设我补充道“数据库是MySQL 5.7表叫users大概有500万行。慢SQL是SELECT * FROM users WHERE age 30 AND city ‘Shanghai’ ORDER BY created_at DESC LIMIT 100;没有索引。应用可以修改。目标是解决当前问题并为未来增长到数千万行做准备。”第四步AI给出针对性方案在获得了清晰的上下文后AI才会开始输出高质量的、可操作的方案立即优化建议在(city, age)上创建复合索引并解释为什么这个顺序最优最左前缀原则高筛选度的city在前。建议考虑覆盖索引或单独在created_at上索引用于排序。中期准备建议使用pt-query-digest工具持续分析慢日志。介绍如何通过数据库读写分离来分摊压力。长期架构介绍当单表达到数千万时可以考虑的分区表Partitioning策略例如按created_at范围分区或者引入分库分表中间件如ShardingSphere的利弊并给出简单的演进路线图。整个流程从一次模糊的请求变成了一次结构化的、信息充分的技术讨论。promptly-prompt充当了那个在你思路不清时逼你和AI把问题定义清楚的“严师益友”。4. 高级技巧、自定义与集成方案4.1 调整复杂度评分规则以适应个人工作流默认的评分规则是一个很好的起点但每个人的工作习惯不同。你可能发现某些对你来说很简单的请求总被拦截或者某些复杂的请求却溜走了。这时你可以通过修改intercept.py脚本来自定义规则。找到并编辑核心脚本 脚本的核心评分逻辑通常在一个名为calculate_complexity_score(prompt_text)的函数里。以下是一个简化的示例展示了如何修改# 在 intercept.py 文件中找到类似下面的函数定义 def calculate_complexity_score(text): score 0 words text.split() # 1. 长度评分 (你可以调整阈值) if len(text) 120: # 原为80 我提高到120对长文更宽容 score 2 elif len(text) 60: # 原为40-80 我调整为60-120 score 1 # 2. 多步骤词汇 (你可以增加或修改关键词列表) step_indicators [then, 然后, next, after that, 接着, finally, 并且还要] # 添加你自己常用的词汇例如 ‘另外’ step_indicators.append(另外) for indicator in step_indicators: if indicator in text.lower(): score 2 # 你可以调整每个词的权重比如改为 1 # 3. 模糊词汇 (同样可以自定义列表) ambiguity_indicators [maybe, 大概, 可能, perhaps, somehow, 应该] # 移除你觉得不敏感的或添加新的 # ambiguity_indicators.remove(大概) for indicator in ambiguity_indicators: if indicator in text.lower(): score 1 # 4. 代码块检测 (如果你经常讨论代码可以降低其负分权重) if in text: score - 1 # 原为 -2 我改为 -1 # ... 其他规则 return score # 同时找到触发拦截的阈值判断通常是一个条件语句 # if total_score 3: # 你可以修改这个阈值 if total_score 4: # 例如我改为4分才触发让技能更“安静” inject_disciplines() else: pass_through()自定义思路提高阈值如果你经常处理冗长的文档分析或代码审查本身就很长但指令明确可以提高长度相关的分值或提高总阈值减少打断。修改关键词如果你的工作领域有特定行话如“请对齐一下OKR”、“做个归因分析”可以将这些词加入“多步骤”或“模糊”列表让AI对这些指令更敏感。调整权重如果你认为“包含代码”并不意味着简单有时是复杂的代码修改请求可以减少其负分甚至改为正分。实操心得版本管理你的修改如果你决定自定义intercept.py强烈建议使用Git来管理你的更改。在修改前先git init初始化一个本地仓库或者在你的配置目录下进行版本控制。这样当技能原作者更新时你可以清晰地合并更新避免自定义内容丢失。一个简单的做法是将官方仓库fork到你自己的GitHub账户然后克隆你的fork进行修改并通过git remote跟踪上游更新。4.2 与其它Claude Code技能或工作流集成promptly-prompt是一个底层钩子它可以与其他技能协同工作构建更强大的自动化工作流。场景一与代码生成/检查技能结合假设你还有一个自动生成代码注释的技能。工作流可能是promptly-prompt先拦截你的模糊请求“为这个函数加注释”并迫使AI澄清“你需要的是文档字符串docstring、行内注释还是两者都要注释的详细程度如何”在你明确需求后请求被放行。下一个钩子或同一个会话中的AI开始执行具体的代码注释生成任务因为上下文已经清晰生成质量会更高。场景二作为复杂Agent流程的“需求网关”如果你在构建基于Claude Code的多步骤智能体Agent可以将promptly-prompt置于流程的最前端。任何用户输入都先经过它的“理解与澄清”层输出的结构化澄清信息能力边界、澄清后的需求、推荐方法可以作为后续专门技能如SQL优化技能、API设计技能的标准化输入。这能极大提升复杂Agent的稳定性和输出质量。技术实现思路intercept.py脚本的输出不仅仅是注入的文本它的退出状态码或输出到stderr的信息可以被其他脚本捕获。你可以设计一个更复杂的钩子链在UserPromptSubmit中依次调用多个处理脚本promptly-prompt负责需求解析并将其结果以结构化的格式如JSON写入一个临时文件供后续技能读取。4.3 在团队中推广与制定使用规范对于团队协作统一使用promptly-prompt能显著提升与AI协作的沟通质量和代码一致性。统一安装将安装步骤写入团队的新成员 onboarding 文档。可以通过共享一个配置好的settings.json文件片段或者提供一个团队内部的安装脚本。制定提示词规范结合promptly-prompt的机制可以制定团队的“AI协作提示词指南”简单指令直接发对于git,ls, 读取文件等操作无需特殊处理。复杂任务先自省在提出复杂请求前团队成员可以下意识地先按“能力边界、需求澄清、方法搜索”三个维度在脑子里过一遍把关键信息直接写在最初的提示里。即使忘了promptly-prompt也会补上这个过程。利用澄清环节鼓励团队成员认真阅读AI提出的澄清问题并给出精确、详细的回答。这本身就是一个极好的需求梳理过程。案例库建设收集和分享那些经过promptly-prompt澄清后AI给出的高质量回答案例。这能帮助团队成员直观地理解“好上下文”如何产生“好结果”并学习如何更有效地与AI交互。5. 常见问题、故障排查与效果评估5.1 安装与运行问题排查表问题现象可能原因解决方案安装后Claude Code会话中没有任何变化复杂请求未被拦截。1.settings.json配置文件路径错误或格式错误。2.intercept.py脚本路径在配置中写错。3. Python环境问题脚本无法执行。1. 检查~/.claude/settings.json文件是否存在且JSON格式正确。可用在线JSON校验工具检查。2. 使用which python3确认Python3路径并在配置中使用绝对路径指向intercept.py。3. 在终端手动运行python3 /path/to/intercept.py看是否有语法错误。确保脚本有读取权限。技能被触发但AI输出的纪律文本是乱码或格式错乱。脚本的编码问题或者输出内容包含特殊字符未被正确处理。确保intercept.py文件以UTF-8编码保存。在脚本开头可显式指定# -*- coding: utf-8 -*-。检查注入的文本中是否包含平台不兼容的换行符。所有请求包括非常简单的如ls都被拦截了。复杂度评分阈值 (THRESHOLD) 设置过低或评分规则过于敏感。检查intercept.py中的THRESHOLD变量值通常为3。尝试调高它。或者检查评分函数是否对短句、命令的减分不够。非常复杂的请求却没有被拦截。复杂度评分阈值设置过高或评分规则未能识别你特定领域的复杂特征。调低THRESHOLD值。根据你的工作内容在step_indicators和ambiguity_indicators列表中添加领域关键词。卸载技能后钩子似乎仍在运行。settings.json中的钩子配置未被移除。手动编辑~/.claude/settings.json删除与promptly-prompt相关的UserPromptSubmit钩子配置项。5.2 效果评估与局限性认知使用promptly-prompt几周后我对其效果和边界有了更清晰的认识。积极效果输出质量显著提升AI给出的方案针对性更强考虑更周全减少了因误解需求而产生的无用输出。节省反复沟通时间虽然单次交互的轮次可能变多先澄清再执行但总体上看一次性做对的概率大大增加避免了后续来回修正的巨大时间成本。促进深度思考作为使用者在AI提出那些澄清问题时我自己也不得不更深入地思考自己的需求这是一个非常好的自我审视过程。知识发现“方法论搜索”环节经常能让我了解到一些之前不知道的优秀开源库或设计模式拓展了技术视野。局限性及应对规则引擎的固有局限基于规则的评分无法理解语义。例如一句非常长但只是引用文献的句子可能会被误判为复杂请求。应对可以通过自定义规则增加对“引用块”、“日志输出”等特定模式的识别并给予负分或者坦然接受偶尔的“误报”将其视为一次额外的检查机会。可能打断流畅的思维流当你在进行一连串快速的、探索性的对话时频繁的拦截可能会感觉拖沓。应对对于明确的“探索会话”或“头脑风暴”可以临时禁用该技能通过注释掉settings.json中的配置并重启会话或者设置一个更高的触发阈值。无法替代人类判断AI澄清的问题可能不总是切中要害有时它可能会遗漏真正关键的问题。应对使用者仍需保持批判性思维。把AI的澄清当作一个检查清单Checklist的补充而不是完全依赖它。对超简单任务的开销虽然脚本运行很快50ms但对于海量的、极其简单的自动化任务流理论上存在微小的性能开销。应对在实际使用中这种开销对于交互式编程辅助场景完全可以忽略不计。一个关键的认知转变不要将promptly-prompt视为一个“自动化提示词优化器”而应将其视为一个“强制性的需求对齐会话伙伴”。它的价值不在于让提示词变得更漂亮而在于在错误发生之前建立一道坚固的“理解防火墙”。经过这段时间的实践我已经习惯在提出复杂任务前下意识地在心里预演一遍那三层纪律。这或许才是这个工具带来的、超越工具本身的更大价值——它训练了我更清晰、更结构化地思考和表达需求的能力。