web-dev-skills: Instructions file for Claude Code

Skill 编写规范

本仓库用于开发 Claude Code plugin t-tools。在这里修改的是可触发、可执行、可恢复、可验收的 AI 工程工作流，不是目标项目的业务代码。

规则归属

• skills/ 负责阶段编排、前置校验、状态推进、产物写入和失败恢复。
• agents/ 负责单一角色的具体执行或只读验收，不承担跨阶段编排。
• protocols/ 是跨 skill 和 agent 的共享契约源；状态结构、输出结构、评分规则和调度规则只在这里定义。
• guides/ 承载工程规范和领域实践；skill 只说明何时读取，不复制大段内容。
• scripts/ 承载需要重复执行或必须保持确定性的操作。
• 同一规则只维护一份。先确定规则归属，再通过语义路径引用它。

编写 Skill

• 一个 skill 只负责一个边界清晰的阶段或能力。不要把相邻阶段的实现、测试和验收揉进同一个入口。
• name 使用稳定的 kebab-case；description 同时说明“做什么”和“何时使用”，并与容易混淆的相邻 skill 明确消歧。
• 只写会改变 AI 决策或执行结果的内容。删除通用知识、仓库文件系统已经显而易见的信息和没有实际约束力的说明。
• 根据风险控制自由度：开放性工作给出目标和判断标准；脆弱、可破坏或必须一致的操作才规定固定顺序、命令或脚本。
• SKILL.md 保留入口所需的目标、适用范围、核心流程、门禁、失败处理和资源路由。详细契约放入 protocols/，工程知识放入 guides/，可执行逻辑放入 scripts/。
• 引用必须说明何时读取或执行。避免深层引用链，也不要默认加载当前任务不需要的所有参考文件。
• 涉及阶段产物时，明确输入来源、输出位置、成功条件和下游消费条件。
• 涉及持久化状态时，明确状态转换、可恢复点、重复执行行为以及失败后由谁继续。
• 需要用户裁决的缺口必须暴露给用户；不要把未确认假设写入产物后继续推进。
• 面向目标项目引用插件内部文件时使用 ${CLAUDE_PLUGIN_ROOT}，不要依赖插件安装位置或当前工作目录。

编排与角色边界

• Skill 负责决定下一步、选择 agent、传递必要上下文并汇总结果；不要在 skill 和 agent 中重复实现同一判断逻辑。
• Dev agent 可以实现；test agent 专注测试；accept agent 默认只读验收并输出可复核证据。
• Agent 输入、输出或评分被多个入口使用时，抽取为 protocols/ 契约，不在各调用方分别描述。
• t-prd-check、t-design-check、t-task-check 是可选质量检查。可以在高风险或 AI 输出不稳定时推荐，但不得悄悄变成主链路的强制前置条件。
• Accept 是实现后的验收收口。增加前置检查不能替代或弱化 accept 的职责。
• 纯技术且不改变业务逻辑、产品规则、用户流程或验收目标的方案，才可以绕过 PRD 直接从技术预研进入设计。

修改前后检查

• 修改 skill 前先搜索它引用的 protocol、guide、agent、script，以及引用该 skill 或其产物的下游入口。
• 修改共享状态、输出、评分或调度规则时，更新对应 protocols/，并检查所有消费者；不要只修当前调用方。
• 修改目标项目运行时文件结构时，先检查 ${CLAUDE_PLUGIN_ROOT}/protocols/runtime-boundaries.md 和 ${CLAUDE_PLUGIN_ROOT}/skills/t-init/ 的相关模板。
• 修改命令调用、skill 名称、公开工作流或安装方式时，同步更新 README.md 和 README.en.md。
• 修改插件暴露能力或依赖时，同步检查 .claude-plugin/plugin.json。
• 中文文档是主说明；存在对应英文文档时保持语义一致。

验证

• 把 skill 文本视为行为代码验证，不以 Markdown 可读性代替行为正确性。
• 按变更风险验证正常路径、前置条件缺失、下游门禁、失败恢复和重复执行；只验证受影响的场景，不编造无关测试。
• 新增或修改脚本时直接运行脚本，并覆盖本次变更涉及的错误路径。
• Markdown 链接使用 ${CLAUDE_PLUGIN_ROOT}/scripts/check-markdown-links.py 检查。
• playwright-unified-logger 已迁移为独立仓库，本仓库只按 npm 包名引用它，不维护其源码。
• 发布仍由 ${CLAUDE_PLUGIN_ROOT}/scripts/release.py 和 /t-tools:t-release 约束：语义版本不带 v，git tag 使用 v 前缀。
• 仓库可能有用户未提交改动；不要回滚或覆盖与当前任务无关的内容。