accelint-onboard-openspec

引导配置 OpenSpec

通过对话式访谈引导用户，生成一份完整、针对具体项目的 openspec/config.yaml，并配置为 QRSPI 方法论。

引导配置 OpenSpec 时绝对不要做的事

• 有子 Agent 可用时，绝对不要串行运行代码库推断 — 阶段 3 会为不同的发现领域并行启动子 Agent。对于配置文件分散在多个目录中的代码库，串行扫描会浪费时间。请同时启动全部 4 个发现 Agent。

配套技能

本技能生成 Agent 指令栈中的 项目 DNA 层：关于项目是什么的结构性事实。它与 accelint-onboard-agents 技能配套，后者生成 行为层（AGENTS.md / CLAUDE.md）：Agent 如何行动、沟通和做出决策。

如果在此访谈过程中用户主动提供了行为性内容（提交约定、工作流步骤、决策启发式、工具偏好），请予以确认并引导： "那属于行为性内容 — 它应该放在 AGENTS.md 中。我会在这里记录下来以供参考，但 accelint-onboard-agents 技能才是捕获它的正确位置。" 不要将行为性内容写入 config.yaml。

AGENTS.md / CLAUDE.md  → accelint-onboard-agents skill  → HOW the agent behaves
openspec/config.yaml   → this skill             → WHAT the project is

---

心智模型

配置有两项职责：

1. context: — 注入到每个 AI 产物中的关于代码库的客观事实。可以把它看作让 AI 建议感觉贴合项目的"DNA"。只包含事实，不包含观点。
2. rules: — 针对每个产物（proposal / design / tasks / spec）的检查点，编码了团队的质量标准。

阶段

阶段 0 — 文件状态检测

在提出任何访谈问题之前，先检查 openspec/config.yaml 是否存在并评估其状态。绝不要静默选择模式 — 始终向用户说明检测到的模式，并在继续前确认。

第 1 步 — 检查相关文档

在检测 config.yaml 状态之前，先检查相关的引导文档：

1. 检查 ARCHITECTURE.md
   • 如果存在：读取它以了解部署和基础设施
   • 用它为第 2 轮预先填写答案（基础设施/部署问题）
   • 记录其存在，用于"相关文档"部分
   • 说明："找到了 ARCHITECTURE.md — 我会用它来避免询问那些 已有文档记录的部署问题。"

注意：AGENTS.md 和 README.md 不应影响 config.yml 的生成，因为它们包含 行为/使用信息，而非项目 DNA。

第 2 步 — 检测配置状态

检查相关文档之后，评估配置文件状态：

Does openspec/config.yaml exist?
│
├── No → MODE 1: Create
│         Full interview from scratch.
│
└── Yes → Read the file, then assess:
          │
          ├── Empty or near-blank (schema: line only, no context/rules)?
          │     → MODE 1: Create (with overwrite confirmation)
          │       Ask: "config.yaml exists but appears empty — should I
          │       populate it from scratch, or preserve any current content?"
          │
          ├── Contains recognised fields?
          │   (context: block present, rules: block with known artifact keys)
          │     → MODE 3: Refresh
          │       Abbreviated interview covering only detected drift and
          │       unresolved # TODO: fill in markers.
          │
          └── Contains real content in an unrecognised shape?
                → MODE 2: Import
                  Present three options (A / B / C) before proceeding.

可识别的形态 = 文件是有效 YAML，至少包含一个 context: 键 且其值为非空字符串，或者包含一个 rules: 键且其中至少有一个 已知产物 ID（proposal、specs、design、tasks）。

---

模式 1：创建

运行完整的阶段 1 → 阶段 2 → 阶段 3 → 阶段 4 访谈。这是 全新仓库的理想路径。

---

模式 2：导入

该文件包含真实内容，并非由此 skill 生成。在改动任何内容之前，先向用户提供三个选项：

“这个 config.yaml 已有内容，其结构我无法识别。你希望如何继续？

(a) 重构 —— 我会导入你的现有内容，将其映射到 context: / rules: schema 上，标记出任何应改放到 AGENTS.md 中的内容（工作流步骤、提交约定、工具偏好），进行一次针对性访谈以填补缺口，并生成一个可替换当前文件的合并文件。

(b) 追加 —— 我会进行完整访谈，并在你现有内容旁添加该 skill 的 context: 和 rules: 部分，而不修改已有内容。

(c) 试运行 —— 我会进行完整访谈，并准确展示我本会生成的内容，不对文件系统做任何更改。可在正式提交前用它评估是否合适。”

如果选择选项 (a)：

1. 完整读取该文件。
2. 尽可能将现有内容映射到 context: 子部分和 rules: artifact 键上。
3. 标记出任何违反关注点分离边界的内容（例如提交约定、工作流步骤、工具偏好、Agent 决策启发式）——这些应属于 AGENTS.md。对每一处违规，询问：“这看起来属于行为性内容——它应放在 AGENTS.md 中。要我把它移到那里并从 config.yaml 中删除吗？”
4. 进行一次针对性访谈，仅覆盖缺口（尚无现有内容覆盖的 context 子部分；没有规则的 artifact 键）。
5. 在写入前展示合并预览。现有内容标注为 # from existing file；新内容标注为 # new。

如果选择选项 (b)： 进行完整的 Phase 1 → Phase 4 访谈，并在现有内容旁写入生成的 context: 和 rules: 块。在顶部添加注释：# Sections below added by accelint-onboard-openspec skill。

如果选择选项 (c)： 进行完整的 Phase 1 → Phase 4 访谈，并在对话中展示输出。明确说明：“未更改任何文件。”如果用户满意，可提出以 (a) 或 (b) 重新运行。

---

模式 3：刷新

文件与该 skill 的预期 schema 匹配——它很可能由上一次运行生成。执行一次简短的访谈，仅涵盖以下内容：

1. 提取外部发现 —— 检查调用提示词中是否包含 findings: 列表：

   • 从提示词中解析 findings: 部分（一个由事实性陈述组成的项目符号列表）
   • 每条发现都表述为已知为真的事实，而非指令
   • 示例：“config.yaml 的 Anti-Patterns 部分说要避免轮询，但有两个已归档的变更出于所述原因选择了轮询”
   • 保存这些发现，供第 4 步合并使用

2. 漂移检测 —— 扫描代码库，查找自文件上次更新以来的变更：

   信号	查看位置
   运行时 / Node 版本发生变化	.nvmrc、.node-version、Dockerfile
   新增包 / 框架	package.json 依赖、工作区根目录
   TypeScript 配置收紧	tsconfig.json —— 新增的 strict* 标志
   monorepo 中新增包	pnpm-workspace.yaml、turbo.json
   构建工具发生变化	vite.config.*、tsup.config.*
   新增 CI/CD 工作流	.github/workflows/
   新增领域概念	新增的顶层目录、源码中新增的实体类型
   反模式被弃用	新增的 @deprecated 标签、// TODO: replace 注释

3. 未解决的 TODO —— 找出上一次运行遗留的所有 # TODO: fill in 标记，并将它们作为有针对性的问题提出。

4. 在提出任何问题之前，合并并告知所有发现：

   • 将外部发现（来自第 1 步）与漂移发现（来自第 2 步）以及 TODO（来自第 3 步）合并
   • 向用户展示合并后的列表：

     “我发现了 [N] 条外部发现、[M] 个可能已漂移的上下文部分，以及 [P] 个未解决的 TODO。 我只会询问这些内容——其余部分看起来是最新的。”

   • 如果存在外部发现，请注明其来源（例如，“来自已完成的 OpenSpec 变更”）

5. 在有针对性的访谈之后，写入前仅预览已更改的部分。不要重新输出未更改的部分。

---

阶段 1 — 探索访谈

以对话方式开展访谈。不要一次性抛出所有问题。将它们分成自然的主题轮次。如果用户提到某个技术栈，推断相关工具链并加以确认，而不是再次询问。

第 1 轮 — 项目身份

• 项目名称及其主要用途是什么？
• Monorepo、单一包，还是其他形式？如果是 monorepo，有哪些工作区？
• 构建系统 / 任务编排？（Turbo、Nx、Make、npm scripts、Makefile……）
• 包管理器及任何私有 registry？（npm、pnpm、yarn、bun……）

第 2 轮 — 技术栈 （作为一组问题一起问，不要逐个问）

• 运行时及版本（Node.js 20、Bun 1.x、Python 3.12 等）
• 语言 + 配置（TypeScript strict？exactOptionalPropertyTypes？Python 类型 提示？）
• 框架及版本（React 18、Next.js 14、Express、FastAPI 等）
• 关键领域库（Deck.gl、Apache Arrow、Prisma、SQLAlchemy 等）
• 数据层（Postgres、MongoDB、DynamoDB、ORM/查询构建器、数据格式）
• 测试设置（Vitest、Jest、Pytest、testing-library、Playwright 等）
• Lint / 格式化（ESLint、Biome、Prettier、Black、Ruff 等）
• 构建工具（Vite、tsup、esbuild、Webpack 等）
• CI/CD（GitHub Actions、CircleCI 等）
• 版本管理方式（Changesets、standard-version、conventional commits 等）

第 3 轮 — 架构

• 代码库如何组织？（基于功能、基于分层、领域驱动？）
• 共享 / 工具代码位于何处？
• 是否有路径别名？（@/、~/、src/、#lib/ 等）
• 常用的设计模式？（工厂、仓储、观察者、CQRS 等）

第 4 轮 — 领域概念

• 最重要的 3–5 个领域实体是什么？ 示例提示："对于地图应用，可能是 Layer、Source、Viewport、 Feature、Style。"
• 是否有 AI 应当了解的领域特定术语？
• 是否有在此代码库中含义不明显的专业概念？ 示例："orchestration" 对我们来说有特定含义——它是将样式与数据合并的运行时 层，而不是通用的工作流术语。

第 5 轮 — 性能

• 是否有具体的性能目标？（p95 < 200 ms、60 fps、< 50 MB heap 等）
• 已知的热点路径或性能关键区域？
• 内存或包体积限制？

第 6 轮 — 代码模式

• 导出风格：命名导出、默认导出，还是混合？
• 命名约定：文件、变量、函数、常量？ 示例："文件名用 kebab-case，变量用 camelCase，常量用 SCREAMING_SNAKE_CASE， 类型用 PascalCase。"
• 错误处理：throw、Result<T,E>、错误边界，还是其他方式？
• 测试结构：describe/it、test/expect、AAA 模式？
• 测试文件位置：与源码同目录，还是单独的 __tests__/ 目录树？
• 测试数据的 fixture / factory 方式？

Note: 提交信息约定是一种工作流规程——它属于 AGENTS.md，而不是这里。如果用户现在提到它，先在心里记下，并在 accelint-onboard-agents skill 中提出。不要将它加入 config.yaml。

第 7 轮 — 反模式

• 在代码审查中明确禁止哪些模式？
• 代码库中仍存在但新代码不应效仿的废弃模式？
• 此技术栈特有的已知性能陷阱？

第 8 轮 — 提案规则 你的团队对提案有哪些要求？好的提示：

• "你是否需要提案说明数据库迁移影响？"
• "你是否需要提案标注 API 破坏性变更？"
• "有任何安全审查清单项吗？"

第 9 轮 — 设计规则 需要编码的项目特定设计关注点？好的提示：

• "需要记录 Docker / Kubernetes 资源变更吗？"
• "需要性能影响章节吗？"
• "特定的架构图风格（ASCII、Mermaid）？"

第 10 轮 — 任务规则

• 你如何按包或模块给任务打标签？ 示例：[PKG:auth]、[MODULE:pipeline]、GitHub labels……
• 数据库变更需要回滚计划吗？
• 部署特定的测试门禁（冒烟测试、金丝雀检查）？

---

阶段 2 — 智能默认值

在每个技术栈回答之后，提示相关约定以供确认。可将以下示例作为模式；并视情况扩展到其他技术栈。

Next.js + TypeScript + Tailwind → 建议确认：

• App Router 与 Pages Router，以及适用哪些模式
• Server Component 与 Client Component 的边界规则
• "use client" 指令的放置约定
• API 路由组织（app/api/ 与 pages/api/）

React + Vitest + testing-library → 建议确认：

• 优先使用 userEvent 而非 fireEvent
• screen 查询优先级（role > label > testid）
• 用于 providers 的 render 包装器

Python + FastAPI → 建议确认：

• Pydantic v1 与 v2（字段验证器语法不同）
• 数据库会话的依赖注入（Depends）
• Alembic 迁移工作流
• lifespan 与 startup/shutdown 事件钩子

Node.js + Prisma → 建议确认：

• prisma.$transaction 模式
• 软删除与硬删除约定
• 迁移命名约定

---

阶段 3 — 并行代码库推断

访谈结束后，并行启动发现子 Agent，以填补剩余的配置缺口。所有配置部分都是承重的——缺失字段会降低每一个下游 AI 产物的质量，因此推断始终优于省略。

并行启动发现子 Agent——不要串行扫描。每个 Agent 专注于一个推断领域，并返回结构化发现。等待所有 Agent 完成，然后在阶段 4 之前合并结果。

同时启动以下 Agent：

Agent A — 技术栈与构建工具

• 运行时 / Node 版本：.nvmrc、.node-version、package.json#engines、Dockerfile
• TypeScript 配置：tsconfig.json（compilerOptions 标志、paths 别名）
• 包管理器：package-lock.json、yarn.lock、pnpm-lock.yaml、bun.lockb
• Monorepo 工作区：package.json#workspaces、pnpm-workspace.yaml、turbo.json、nx.json
• 构建工具：vite.config.*、webpack.config.*、tsup.config.*、esbuild 脚本
• 返回：运行时版本、TS 配置标志、包管理器、工作区列表、构建工具

Agent B — 测试与代码质量

• 测试框架：vitest.config.*、jest.config.*、pytest.ini、pyproject.toml#tool.pytest
• Linting / 格式化：.eslintrc*、biome.json、.prettierrc*、ruff.toml
• 测试结构：示例测试文件——describe/it 嵌套深度、文件相对于源文件的位置
• 测试文件类型检查：CI 脚本、package.json——检查 tsc --noEmit 是否在 *.test.ts 文件上运行
• 基于属性的测试：检查依赖中是否有 fast-check
• Vitest mock 清理：vitest.config.ts——检查 clearMocks、mockReset、restoreMocks
• 返回：测试框架、代码质量工具、测试结构模式、类型检查配置

Agent C — 架构与代码模式

• 架构组织方式：src/ 或工作区根目录的目录树——推断是基于功能还是基于分层
• 路径别名：tsconfig.json#compilerOptions.paths、vite.config#resolve.alias
• 设计模式：示例源文件——查找工厂函数、仓库对象、观察者钩子
• 导出风格：抽取 3–5 个源文件；统计具名导出与默认导出
• 命名约定：抽取文件名、导出的标识符；描述你所观察到的内容
• 错误处理：Grep 查找 throw、Result、Either、tryCatch、错误边界组件
• TypeScript 基线模式：如果存在 tsconfig.json，则标记应包含 TS/JS 基线模式
• 返回：架构风格、路径别名、设计模式、导出约定、命名模式、错误处理方法

Agent D — CI/CD 与版本管理

• CI/CD：.github/workflows/、.circleci/、Jenkinsfile
• 版本管理：.changeset/、CHANGELOG.md、commitlint.config.*、.releaserc*
• 反模式：标记为 off 或 warn 的 eslint 规则覆盖、形如 // TODO: replace 的注释、@deprecated
• 返回：CI/CD 平台、版本管理方式、已记录的反模式

所有 Agent 完成后： 将它们的发现合并为统一的推断映射。 将每个字段标记为 INFERRED [source] 或 UNKNOWN。标记为 UNKNOWN 的字段 应在配置预览中标记为 # TODO: fill in。

对于每个通过推断解析的字段，在预览中通过末尾注释注明来源，例如：

- Runtime: Node.js 20 LTS   # inferred from .nvmrc
- Language: TypeScript 5.4, strict, exactOptionalPropertyTypes   # inferred from tsconfig.json

如果某个字段确实无法推断（例如性能目标、领域概念、团队特定规则）， 请用 # TODO: fill in 标记它，而不是省略它。用户可以在查看预览后解决这些问题。不要 静默丢弃某个部分——一个显式的 TODO 是行动的提示；一个缺失的部分 则是不可见的缺口。

---

阶段 4 — 生成

1. 在写入任何内容之前，先展示带标注的完整配置预览。 推断出的值会附带其来源注释；未解析的字段会附带 # TODO: fill in。这让用户能完整了解每个字段的置信度。
2. 询问：“看起来对吗？在我写入文件之前，有没有需要修正或补充的部分？”
3. 确认后，写入 openspec/config.yaml（如需要则创建目录），去除推断来源注释 —— 它们仅供审阅，不属于最终文件。对于 Related Documentation 部分： 只包含仓库中实际存在的文件链接。在包含每个文件（ARCHITECTURE.md、AGENTS.md/CLAUDE.md、README.md）的链接之前，先检查其是否存在。
4. 验证生成的 YAML —— 写入后，读回文件并验证：
   • 没有制表符（YAML 要求使用空格缩进）
   • 含特殊字符的值已正确加引号
   • 没有语法错误（未匹配的括号、引号等）
   • 该文件在概念上可解析为有效的 YAML 如果验证发现问题，立即修复并重写文件。
5. 打印一份简要总结，说明配置了什么、哪些是推断的、哪些是直接回答的，以及哪些 # TODO 字段仍需人工输入。

---

YAML 生成安全规则

关键： YAML 语法对特殊字符要求严格。生成 config.yaml 时请遵循以下规则以避免语法错误：

引号要求

规则： 以 YAML 特殊字符开头的值需要加引号。

特殊字符：|、>、"、'、(、)、[、]、{、}、*、&、!、%、@、`

示例：

# Parentheses at start of value
❌ description: (internal) auth module     # Syntax error
✅ description: "(internal) auth module"   # Quoted

# Square brackets (looks like YAML list syntax)
❌ tag: [PKG:auth]                         # YAML thinks it's a list
✅ tag: "[PKG:auth]"                       # Quoted string

# Pipe character (YAML thinks it's block scalar)
❌ pattern: some|other                     # Syntax error
✅ pattern: "some|other"                   # Quoted

# Colon in value (YAML thinks it's a nested key)
❌ note: Time: 5pm                         # Syntax error
✅ note: "Time: 5pm"                       # Quoted

# Value containing quotes - escape with opposite quote type
✅ command: 'npm run "test:unit"'          # Single quotes protect doubles
✅ command: "npm run 'test:unit'"          # Double quotes protect singles

多行字符串处理

对多行内容使用块标量指示符：

# Literal block (preserves newlines) - preferred for context field
context: |
  Line 1
  Line 2
  Line 3

# Folded block (folds newlines into spaces) - rarely needed
description: >
  This is a long
  description that
  flows together.

缩进规则

• 仅使用空格 —— 绝不用制表符
• 缩进一致 —— 通常每级 2 个空格
• 块标量 —— | 或 > 内的内容必须相对于键进行缩进

列表值规则

# Simple list items - no quotes needed for plain text
rules:
  proposal:
    - Keep proposals under 100 lines
    - Include scope boundaries

# List items with special chars - quote them
rules:
  tasks:
    - "Tag with [PKG:name] format"        # Quotes protect [ and ]
    - 'Use "Test:" prefix for validation' # Single quotes protect inner "

验证清单

生成配置后，在脑中验证：

1. 冒号后没有裸的 (、)、|、"、'（除非使用 | 或 > 表示多行）
2. 文件任何位置都没有制表符
3. 全文一致使用 2 空格缩进
4. 所有列表项（-）在其父级内对齐到同一缩进级别
5. 带引号的字符串使用匹配的引号类型

如果违反其中任何一条规则，YAML 将无法解析。

---

配置模板

使用此确切结构。用来自访谈或代码库推断的内容填写每一个 [placeholder]。如果某个字段无法通过这两种方式解析，将其占位符替换为 # TODO: fill in —— 绝不要省略该字段。每个部分都对下游 AI 产物的质量至关重要。

schema: spec-driven

# Project Context
# Injected into every AI-generated artifact (proposal, design, spec, tasks).
# QRSPI principle: objective research layer — facts only, no opinions.

context: |
  # ═══════════════════════════════════════════════════════════════════════════
  # STACK FACTS
  # ═══════════════════════════════════════════════════════════════════════════

  ## Project Identity
  [project name and one-sentence purpose]
  [repo structure: monorepo / single-package / workspaces list]
  [build system and task orchestration]
  [package manager + registries]

  ## Tech Stack
  - Runtime:            [e.g., Node.js 20 LTS]
  - Language:           [e.g., TypeScript 5.4, strict mode, exactOptionalPropertyTypes]
  - Framework:          [e.g., Next.js 14 App Router]
  - Key Libraries:      [domain-specific dependencies with versions]
  - Data Layer:         [databases, ORMs, data formats, query builders]
  - Testing:            [framework, utilities, coverage tooling]
  - Linting/Formatting: [tools and config files in use]
  - Build Tools:        [bundlers, compilers, transpilers]
  - CI/CD:              [platform and key workflow names]
  - Versioning:         [release strategy and changelog tooling]

  ## Architecture Patterns
  - Organisation: [feature-based / layer-based / domain-driven / other]
  - Shared code:  [path to shared utilities / packages]
  - Path aliases: [list of aliases and their resolved paths]
  - Key patterns: [design patterns in common use]

  ## Domain Concepts
  - [Entity or concept]: [one-line definition]
  - [Entity or concept]: [one-line definition]
  - [Entity or concept]: [one-line definition]

  ## Performance Targets
  - [metric]: [target value and context]

  ### TypeScript/JavaScript Performance (if applicable)
  - Hot paths:    [functions executed >1000 times per interaction or >100 times/sec]
  - Frame budget: [for real-time systems: 60fps = 16.67ms, 120fps = 8.33ms]
  - Constraints:  Bounded iteration (explicit limits on loops/queues), O(n) or better algorithmic complexity

  # ═══════════════════════════════════════════════════════════════════════════
  # PATTERNS TO FOLLOW
  # ═══════════════════════════════════════════════════════════════════════════

  ## Code Patterns
  - Exports:         [named / default / mixed — and when each applies]
  - Naming:          [files, variables, functions, constants, types]
  - Error handling:  [throw / Result<T,E> / boundaries / other]
  - Validation:      [approach and library]
  - Constants:       Use `as const` objects, never `enum`
  - Classes:         Prefer functions over classes unless state management required or extending existing class
  - Return values:   Return zero values (empty array, empty string, 0, false) instead of null/undefined
  - Leaf functions:  Leaf functions (bottom of call stack) should be pure — same inputs produce same outputs, no side effects. Centralize state manipulation in parent/orchestrator functions.
  - Type safety:     Avoid `any` (use `unknown` or generics); avoid `enum` (use `as const` objects); use `type` over `interface`
  - Immutability:    Prefer `const`, immutable data structures, pure functions
  - Documentation:   Comprehensive JSDoc for all exported code (@param, @returns, @template, @example)
  - Order:           Internal functions, variables and types should be defined before they are used (internal/export types -> internal/export constants -> internal/export functions)
  - Parameter order: Data-last ordering — place the data being operated on as the final parameter. Enables partial application and composition.
  - Composition:     Use curried functions when the same first parameter(s) recur across call sites.

  ## Architecture Patterns
  - [pattern name]: [brief description of how it's used here]

  ## Testing Patterns
  - Pattern:        AAA (Arrange, Act, Assert) with clear boundaries
  - Property-based: (If available) Use `fast-check` for encode/decode pairs, validators, normalizers, pure functions
  - Test scope:     Never test library internals; never export internals to test them; never mock own pure functions
  - Structure:      [describe/it nesting convention]
  - File location:  [co-located / __tests__ / other]
  - Test doubles:   Hierarchy: real implementation > fakes > stubs > spies > mocks
  - Fixtures:       [factory functions / fixture files / inline data]
  - Assertions:     [preferred assertion style]
  - Nesting:        Max 2 levels of describe blocks — use descriptive test names instead
  - Verification:   MUST run `tsc --noEmit` on test files before marking complete
  - Benchmarks:     [approach if any]

  # NOTE: Commit message convention, PR workflow, and tool preferences
  # are behavioral — they belong in AGENTS.md, not here.

  # ═══════════════════════════════════════════════════════════════════════════
  # PATTERNS TO AVOID
  # ═══════════════════════════════════════════════════════════════════════════

  ## Code Anti-Patterns
  - Using `any` instead of `unknown` or generics
  - Using `enum` instead of `as const` objects
  - Using `interface` when `type` works (prefer type)
  - Returning `null`/`undefined` instead of zero values (empty arrays, empty strings, 0, false)
  - Not validating external data with schemas
  - Deep nesting instead of early returns

  - [anti-pattern]: [why it's banned or deprecated]

  ## Performance Anti-Patterns
  - Chaining array methods (`.filter().map().reduce()`) — use single reduce pass
  - Using `Array.includes()` for repeated lookups (use `Set.has()` for O(1) lookups)
  - Recomputing constants inside loops (hoist invariants outside)
  - Unbounded loops or queues (set explicit limits to prevent runaway resource consumption)
  - Placing `try/catch` in hot paths (V8 cannot inline, 3-5x slowdown)

  - [anti-pattern]: [why it's banned or deprecated]

  ## Testing Anti-Patterns
  - Testing library internals (e.g., verifying Array.prototype.map works)
  - Exporting internal functions just to test them
  - Loose assertions in tests (toBeTruthy, toBeDefined)
  - Nested describe blocks >2 levels deep
  - Testing implementation details instead of behavior

  - [anti-pattern]: [why it's banned or deprecated]

  ## Documentation Anti-Patterns
  - Missing JSDoc on exported functions/types
  - Documenting HOW instead of WHAT/WHY in JSDoc
  - Vague comment markers (`// TODO: fix this` instead of `// TODO: Replace with binary search for O(log n)`)

# ═══════════════════════════════════════════════════════════════════════════
# PER-ARTIFACT RULES
# ═══════════════════════════════════════════════════════════════════════════

rules:
  proposal:
    # QRSPI: Scope definition, not a plan.
    - State the requirement or ticket driving this change
    - Define scope boundaries — explicitly list what is OUT of scope
    - Keep under 100 lines (tight and focused)
    [user-specific proposal rules]

  design:
    # QRSPI: The "brain surgery" checkpoint — reviewed before any code is written.
    # Target ~200 lines capturing current state, desired state, open questions.

    # Required sections (in this order):
    - Start with "Current State": what the code does today, key files, entry
      points, relevant data flows
    - "Desired End State": what changes after this work, what stays the same
    - "Patterns to Follow": ONLY if specific files/functions to reference exist
      for this change's domain
    - "Patterns to Avoid": ONLY if specific anti-patterns apply to this change
    - "Open Questions": genuine uncertainties requiring human input. If none,
      state explicitly "No unresolved questions."
    - "Resolved Decisions": numbered (Decision 1, Decision 2…) with Choice,
      Rationale, Alternatives Considered

    # Technical depth:
    - Use ASCII diagrams for data flows, state machines, architecture
    - Call out performance implications where relevant
    [user-specific design rules]

    # Constraints:
    - Keep under 250 lines total

  tasks:
    # QRSPI: Vertical slicing for early failure detection.

    # Vertical slicing (strong preference):
    - Order as vertical slices — each task delivers a testable end-to-end path
    - Do NOT group by architectural layer unless explicitly justified
    - Horizontal (layer-by-layer) only for pure infrastructure; include
      justification in the task description when used
    - Each task MUST include an explicit "Test:" line describing what to verify
      before proceeding to the next task
    - Prefer 3–5 major slices; more than 5 suggests scope is too large

    # Granularity:
    - Max 2 hours per task; break larger work into subtasks
    [user-specific task tagging, e.g., [PKG:name] or [MODULE:name]]
    - Call out inter-task dependencies explicitly
    [user-specific rollback requirements]
    [user-specific deployment test gates]

  spec:
    - Use Given/When/Then for behaviour specifications
    - Include concrete example data relevant to the domain
    - Document edge cases explicitly
    [user-specific spec rules]

# ═══════════════════════════════════════════════════════════════════════════
# RELATED DOCUMENTATION
# ═══════════════════════════════════════════════════════════════════════════
# Include only files that actually exist in the repository:
# - ARCHITECTURE.md: System overview, deployment, component interactions, data flows
# - AGENTS.md: Agent behavior rules, workflow procedures, communication style
# - README.md: Installation, quick start, usage guide

---

交互原则

• 对话式，而非审问式。 将相关问题合并到一轮中。使用自然语言，而非罗列式表单。
• 推断并确认。 “你提到了 Vitest —— 我会假定你在组件测试中使用 @testing-library/react；对吗？”比从头询问更好。
• 示例可减少歧义。 当询问命名约定时，先给出一个示例，以便用户进行模式匹配。
• 迭代式。 让用户修改答案。不要把他们锁定在第一次回答中。
• 写入前先预览。 在改动文件系统之前，始终展示完整的生成配置并获得明确确认。
• 先推断再询问，先询问再省略。 对任何未回答的字段，始终尝试进行代码库推断。如果推断失败，浮现一个 # TODO，而不是丢弃该部分。带有明确 TODO 的配置是可操作的；缺少部分的配置会悄然降低它所驱动的每一个产物的质量。