一家公益剧团把售票页面、演出资料和内部排班工具放在同一仓库里。维护者用 Claude Code 改动无障碍席位说明时，经常重复解释项目结构，跑较长检查又容易错过等待确认的时点。改进工作流可以围绕三个可验收的目标展开，让查找命中正确代码，让通知带回明确状态，让每次修改有范围和验证记录。以下使用练习分支及虚构演出数据，所有配置先在隔离副本中验证。
先做一份代码检索基线
给助手三个小任务。查找席位说明从哪里进入页面，找到取消订单后恢复名额的实现，以及定位打印票根日期的格式化入口。为每个任务保存正确的文件、调用关系和一条可以复跑的检查。先用仓库已有的文件搜索和文本检索完成，记录耗时、读过的文件数以及误命中的原因。根据这些结果判断是否需要语义索引。例如业务叫「无障碍席位」，代码中却采用另一种命名，语义匹配可能有帮助；构建输出重复命中，则先把生成目录从检索范围排除。
决定建立索引时，核对所用工具实际支持的语言、文件类型、排除规则和数据去向。把源码、演出资料和生成产物分别指定范围。含账户配置、真实订单和日志的目录先按项目的数据规则处理。为索引记录仓库版本和更新时间，改完代码后用同一问题验证结果能否指向新位置。删掉一段旧实现时也要检查它是否还出现在候选中，防止助手按过期片段做修改。
检索结果需要能回到文件与具体代码。让助手先列候选及理由，再打开当前文件核对调用方、输入和输出。语义匹配用于缩小范围，实际差异仍基于当前源码。为一次改动记录「席位说明」到页面组件再到文案数据源的路径。若结果只给出一段没有版本和位置的摘要，先补上来源，再交给后续实现步骤使用。
通知要告诉维护者下一步能做什么
先列出需要关注的状态。长检查结束、工具等待批准、运行失败需要处理，都可以让维护者回到具体任务。内容以项目名、任务编号、状态和本地记录位置为主，避免把完整用户输入、源码或票务信息放进桌面提醒或外部渠道。多任务并行时用不同编号，看到通知就能找到原会话和对应分支。
Claude Code 的 Hooks 文档提供事件、输入和返回约定。选择通知方案前，按当前版本核对它支持哪个事件、配置作用域和执行方式。先让一个本地处理程序只写入时间、事件类型及任务编号，观察实际触发，再接桌面通知。设置执行时限并检查失败是否拖住原任务。完成提醒、等待输入提醒和任务失败的含义分别验收，不能因为一个通知出现就认定所有状态都已覆盖。
在练习任务中跑一次短检查、一项等待确认的动作和一条故意失败的检查。对照会话状态与记录确认通知没有把「等待批准」写成「已完成」。接着启动两个项目任务，验证通知不会混淆项目和编号。若桌面没有弹出提醒，先看处理程序是否被调用，再检查配置是否加载、宿主与版本是否支持该事件，以及系统通知设置。若日志有事件而提示没有出现，集中排查通知呈现层。
项目指令写成能落实的工作约定
把常用命令、代码入口、数据约束和验收条件放在项目合适的说明位置。使用 CLAUDE.md 时按官方记忆文档确认加载范围，避免在不同层级放互相冲突的要求。说明应回答怎样启动练习服务、运行哪条检查、哪些路径需要特殊审核、哪些生成文件由构建产生。对每条命令实际执行一次，记录依赖和成功信号。只有「请保证质量」的要求很难转成具体检查。
给席位文案修改一份有限的任务卡，写明目标读者、要改变的字段、允许的文件与验收方法。先请助手阅读相关说明，复述调用路径并提出改动计划。计划确认后生成小差异，运行现有检查，再打开预览页核对文字、换行和键盘访问。记录实际执行、未运行项和原因。发现任务影响退款或库存逻辑时，先找清影响面，再由维护者决定是否纳入这次改动。
会话越来越长时，整理一份可以接手的状态记录。保留目标、已确认的事实、修改文件、验证结果、未解决问题和下一步。证据要指向分支与当前文件版本。新会话从记录开始时，先检查工作区差异，再复跑一条关键检查。若摘要说文案已改而当前分支没有对应差异，回到实际文件核对，避免把另一会话的进展当成当前结果。
拆分任务时给每份产物一个身份
对于相互独立的工作，可以让不同工作单元分别查找票根日期、检查席位文案和核对排班导出，但每项都要有输入版本、任务边界和交付格式。共享文件由维护者或单一整合步骤合并，候选结果写到各自的位置。需要顺序依赖的任务先等事实确认，再让下一步改代码。评估拆分是否有效时，看端到端时间、返工和冲突，而不是只看同时启动了几个任务。
代码审阅记录具体问题的位置、触发条件和后果。对一项日期显示问题，让复核者在旧实现上跑失败样本，再在新实现上复跑，验证是否捕捉真实差异。把最终版本交给另一位同事，要求他按任务卡找到修改、跑检查并打开预览。若必须翻完整聊天才能理解验证方法，补足交付记录。
技能选用与一次验收示例
索引配置能力用于解释索引范围、更新方式和候选位置。给它三条已标注的检索问题，检查它能否找到当前源码并暴露缺口。通知配置能力用于把真实事件转换成可追踪的状态提示，先验收它是否只读取必要字段、是否会调用外部服务、失败时如何返回。工作流指导能力可帮整理 CLAUDE.md、任务卡与审阅步骤，产物需要与仓库实际命令一致。候选的标题和安装次数无法代替这些小样检查。
以席位说明为例，先从问题定位到当前文案数据源，记录索引版本。修改说明后跑检查并预览，等待输入时收到带任务号的提示。审核者提出一处换行调整，助手更新同一份任务记录，复验页面后提交交接包。包内包括差异、检查结果、预览位置和未决项。把这个流程再交给一位新维护者复跑，确认通知、索引和说明共同减少了重复解释。
常见问题
索引没有更新时还能改代码吗？
先打开实际源码确认候选位置和版本。若检索结果过期，标记并更新索引，再回放基线问题。小范围任务也可用现有搜索完成，但交付记录要指向实际修改的文件。
配置了通知，长任务结束却没有提醒怎么办？
先核对真实事件是否产生、配置是否被当前宿主加载，再看处理程序的执行和系统通知。将任务完成与等待确认分别测试，保留版本和事件类型，便于判断是支持范围还是处理失败。
其他 Agent 能直接用同一份配置吗？
分别检查宿主的指令文件、事件系统和技能发现方式。复用项目规则时，按目标工具的配置格式保存，用同一练习任务核对行为。命令能执行、说明能加载和技能能触发是不同的验收点。