Communitygithub.com

Luijaa/web-template

在编写任何代码之前,为新系统或大型功能进行设计——通过多轮访谈、编写模板化的 docs/design/<slug>.md 文件、记录 ADR 和术语表,执行 make docs-check 检查,并提交仅含文档的 PR 等待审批。当需要设计某物时使用,或当 /new-feature 发现功能规模较大时自动调用。

web-template 是什么?

该技能旨在引导 AI 助手遵循预定义的 `docs/design-process.md` 流程,在编写任何代码之前进行结构化设计。它通过多轮访谈收集需求与决策,处理边缘案例,并逐步将设计决策写入文档模板。技能涵盖了从评估设计必要性、创建分支和设计文件、编写架构决策记录(ADR)、维护术语表,到运行 `make docs-check` 验证文档一致性、提交仅含文档的 Pull Request,以及最终根据审批状态更新文档和生成后续任务的全过程。它主要适用于使用 Markdown 文档和 Makefile 的 Git 仓库,支持通过环境变量或默认路径指定 `web-template` 脚本位置。其核心价值在于强制进行设计优先的开发流程,减少因仓促编码导致的返工,并确保所有设计决策和架构变更都有清晰的记录和审批路径。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Luijaa/web-template/tree/HEAD/.agents/skills/design

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Design: $ARGUMENTS

严格按照 docs/design-process.md 执行每个步骤——该文件是本技能的规则所在,此技能仅编排任务顺序。若两者冲突,以该文件为准。

  1. 是否需要设计 — 对照 docs/design-process.md 第 1 节表格进行评估
    • 不需要:用一行说明原因,然后回退到 new-feature
    • 不确定:先询问用户
  2. 开始(第 3.0 节):创建 epic issue(标签 design),分支 docs/<id>-design-<slug>,复制 docs/design/template.md → docs/design/<slug>.md(命名为 system.md 或 <epic 编号>-<slug>.md),设置 status: draft,并在 docs/design/README.md 中新增一行
  3. 阅读后再提问:CONTEXT.md、docs/adr/、docs/architecture.md、docs/design/ 下的其他设计文档——自己能查到的信息自己去查,不要提问
  4. 多轮访谈(第 3.1 节),格式为 Qn — 主题: 问题 + 每个问题给出 建议: …,每轮必须包含 1–2 个边缘案例——完整遍历 A–H 分支(第 3.2 节),并在审批点 1、2(系统设计)、3 停下来等待用户
  5. 每轮结束后写入文件:更新设计文件中的对应章节,在 CONTEXT.md 中添加新术语,在 docs/adr/ 中创建状态为 proposed 的 ADR(并更新索引),若容器或外部系统发生变化则更新 docs/architecture.md 中的 C4 模型
  6. 检查(第 3.3 节):必须通过 make docs-check(若仓库 Makefile 中尚无该目标,则运行 python3 <web-template 路径>/scripts/check-docs.py <repo>——对于 Hermes 团队:/home/opc/projects/web-template)并自行完成检查清单,然后将状态设为 proposed
  7. 仅含文档的 PR:标题格式 docs(design): <slug>,正文包含 Refs #<epic>、未决选项的摘要以及 ## CHANGELOG 节(内容为 -)——禁止包含代码,禁止合并
  8. 审批(第 3.4 节):当审批者提交后,将状态更新为 approved 并添加 approved-by 字段,同时在同一个 PR 中将 ADR 状态改为 accepted(需通过 make docs-check),然后由审批者合并
  9. 合并后(第 3.5 节):按照第 13 节主题逐个创建子 issue,每个子 issue 链接到 epic 和设计文件——编码工作从 new-feature 开始

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

相关技能