style-anchors-collection

风格锚点合集

系统地识别、记录和整理展示技术要求中认可模式的代码示例。创建一个结构化的风格锚点库，供整个实现过程使用。

前置条件

• 已完成 technical-requirements.yaml
• 可选：能够访问现有代码库或参考仓库

目的

风格锚点是作为实现模板的具体代码示例。它们通过以下方式避免偏离预期：

• 在开始编码前确立认可的模式
• 提供具体的文件:行号引用，而不是抽象描述
• 记录每种模式的使用时机和方法
• 为项目创建可复用的模式库

收集流程

步骤 0：确定输出目录

如果未将目录作为参数提供，请提示用户：

“应将风格锚点创建在哪里？（这应与需求文档使用相同的基础目录）”

等待用户回复。将提供的路径存储为 base_directory。

步骤 1：加载技术上下文

1. 加载 {base_directory}/requirements/technical-requirements.yaml

2. 解析关键架构模式：

   • 架构模式（单体、微服务等）
   • 技术栈（语言、框架、库）
   • 测试策略（TDD、框架）
   • 数据模型方法（数据库、架构模式）
   • API 模式（REST、GraphQL 等）
   • 安全模式（身份验证、验证）

3. 确定要收集锚点的模式类别（典型类别）：

   • 服务 - 带依赖注入的服务层模式
   • 测试 - 测试结构、模拟、TDD 模式
   • 验证 - 输入/输出验证、架构验证
   • API - 端点处理器、中间件、路由
   • 数据访问 - 数据库查询、ORM 模式、迁移
   • 错误处理 - 错误类型、错误传递、恢复

步骤 2：展示收集计划

向用户显示已确定的类别：

## Style Anchors Collection

Based on your technical requirements, I'll collect code examples for these pattern categories:

1. Services (Effect.Service pattern with dependency injection)
2. Testing (Effect service testing with @effect/vitest)
3. Validation (Schema.Class validation patterns)
4. Error Handling (Tagged errors with Effect)

For each category, I'll ask you to provide:
- File path to exemplar code
- Line range (e.g., 10-50)
- What the pattern demonstrates
- When to use it

You can provide examples from:
- Your current codebase
- A reference repository (will link to it)
- Suggest "none" to skip a category

询问：“准备开始收集了吗？”

等待确认。

步骤 3：交互式收集

针对每个已确定的类别：

3.1. 询问源文件：

## Category: [Category Name]

What file demonstrates your preferred [pattern description]?

Options:
1. Provide file path from current project (e.g., src/services/UserService.ts)
2. Provide URL to reference repository file
3. Type "none" to skip this category
4. Type "help" for guidance on what makes a good style anchor

Your answer:

3.2. 询问行范围：

What line range should I reference?

Format: Start-End (e.g., 10-50)
Or: Single line number (e.g., 25)
Or: "all" for entire file

Your answer:

3.3. 如果文件可访问，则读取并显示：

## Code Preview

[Display the code from specified lines]

Does this look correct? (yes/no/adjust)

如果选择“调整”，则返回行范围问题。

3.4. 询问该模式展示了什么：

What does this code example demonstrate?

Examples:
- "Service pattern with Effect.Service and dependency injection"
- "TDD test structure using it.effect from @effect/vitest"
- "Schema validation with proper error handling"

Your answer:

3.5. 询问何时使用：

When should developers use this pattern?

Examples:
- "When creating any service class in the service layer"
- "When testing Effect-based services"
- "When validating external input data"

Your answer:

3.6. 生成锚点 ID：

根据模式名称创建锚点 ID（kebab-case，例如 service-pattern、test-effect-services）

3.7. 确认并继续：

✓ Collected anchor: [anchor-name]

Continue to next category? (yes/no/review)

步骤 4：生成输出

4.1. 创建目录结构：

mkdir -p {base_directory}/artifacts/style-anchors

4.2. 生成 index.yaml：

创建 {base_directory}/artifacts/style-anchors/index.yaml，其中包含：

• 版本和元数据
• 包含已收集锚点的类别
• 带源引用的锚点定义
• 将模式映射到任务类型的使用矩阵
• 总数和收集日期

4.3. 生成单独的 .md 文件：

对于每个已收集的锚点，创建 {base_directory}/artifacts/style-anchors/[anchor-id].md，其中包含：

• YAML frontmatter（id、名称、类别、标签、创建日期）
• 概述部分
• 源引用
• 代码示例（如果文件可访问，则从文件中提取）
• 展示内容
• 使用时机
• 模式要求（根据最佳实践推导）
• 应避免的常见错误（根据最佳实践推导）
• 相关锚点（交叉引用）

4.4. 填充模式要求和常见错误：

使用 implementation-plan-best-practices 中的知识添加：

• ✓ 模式要求：3-7 条针对该模式的必做事项
• ❌ 常见错误：3-7 条应避免的反模式

步骤 5：总结

显示收集摘要：

## Style Anchors Collection Complete ✓

**Directory:** {base_directory}/artifacts/style-anchors/

**Collected Anchors:** [count]

📁 Categories:
  - Services: [n] anchors
  - Testing: [n] anchors
  - Validation: [n] anchors
  - Error Handling: [n] anchors

📄 Generated Files:
  ✓ index.yaml (master index with usage matrix)
  ✓ [anchor-1].md
  ✓ [anchor-2].md
  ✓ [anchor-3].md

These anchors will be automatically referenced by implementation-planner
when generating task instructions.

Next Step: Run /implementation-planner to generate milestones and tasks

输出格式

index.yaml 结构

主索引文件包含：version、project、generated、technical_requirements_ref、categories（每个类别包含 id、name、description、anchors 列表）、anchors（每个锚点包含 id、name、file、category、来源引用、适用规则、标签）、usage_matrix（将架构模式和任务类型映射到推荐锚点），以及 meta（计数和日期）。

单个锚点 .md 结构

每个锚点文件包含：YAML frontmatter（id、name、category、tags、created），以及 Overview、Source Reference、Code Example、What This Demonstrates、When to Use、Pattern Requirements、Common Mistakes to Avoid、Related Anchors 和 Test Coverage 部分。

请参阅 references/output-spec.md，了解 index.yaml 和单个锚点文件的完整规范，包括所有字段、格式规则和 usage matrix 结构。

请参阅 references/example.md，查看完整的锚点文档示例。

模式要求和常见错误生成

服务模式：

要求：

• ✓ 所有服务方法都必须返回 Effect 类型
• ✓ 使用 Effect.gen 处理异步操作
• ✓ 使用带标签的错误进行失败处理，不要抛出异常
• ✓ 处理前使用 Schema.decode 验证输入
• ✓ 在 dependencies 数组中声明所有依赖项

常见错误：

• ❌ 使用 async/await，而不是 Effect.gen
• ❌ 抛出错误，而不是使用 Effect.fail
• ❌ 未通过依赖注入直接访问数据库
• ❌ 跳过输入验证
• ❌ 对外部数据使用 any 或类型断言

测试模式：

要求：

• ✓ 对 Effect 测试使用来自 @effect/vitest 的 it.effect
• ✓ 在测试设置中提供所有服务依赖项
• ✓ 测试成功和失败两种情况
• ✓ 使用能说明行为的描述性测试名称
• ✓ 遵循 TDD：先编写测试，再实现代码

常见错误：

• ❌ 对基于 Effect 的代码使用常规 it()
• ❌ 未提供必需的服务依赖项
• ❌ 只测试正常路径，忽略错误
• ❌ 使用“test 1”或“it works”等含糊的测试名称
• ❌ 为了让有缺陷的实现通过而修改测试

验证模式：

要求：

• ✓ 对所有数据验证使用 Schema.Class
• ✓ 在系统边界处验证（用户输入、外部 API）
• ✓ 返回验证错误，不要抛出异常
• ✓ 提供有帮助的错误消息
• ✓ 绝不对外部数据使用类型断言

常见错误：

• ❌ 使用类型断言而不是验证
• ❌ 抛出通用错误，而不是验证错误
• ❌ 验证内部函数参数（信任内部代码）
• ❌ 跳过外部输入验证
• ❌ 对外部数据使用 any 类型

错误处理模式：

要求：

• ✓ 使用带标签的错误（通过自定义错误类调用 Effect.fail）
• ✓ 在错误对象中包含上下文（ID、值）
• ✓ 使用 Effect 传播错误，不要捕获并隐藏错误
• ✓ 在使用位置附近定义错误类型
• ✓ 在函数签名中记录预期错误

常见错误：

• ❌ 抛出错误，而不是使用 Effect.fail
• ❌ 使用字符串错误消息，而不是类型化错误
• ❌ 捕获并忽略错误
• ❌ 错误消息过于笼统，缺少上下文
• ❌ 未记录函数可能产生的错误

用法矩阵生成

将技术要求映射到锚点建议：

根据 architecture.pattern：

• effect-based-services → service-pattern、test-pattern、error-handling
• schema-validation → validation-schema、api-validation
• rest-api → api-pattern、validation-schema、error-handling

根据任务类型：

• code → 对应层的主要模式 + 验证 + 错误处理
• test → test-pattern + 被测试的模式
• api → api-pattern + validation-schema + error-handling
• docs →（通常不需要锚点）
• config →（通常不需要锚点）

最佳实践

优质风格锚点的特点

1. 具体 - 使用真实文件路径，而非抽象描述
2. 明确 - 标注行号以提高精确度（20-50 行为宜）
3. 完整 - 展示完整模式，而不只是代码片段
4. 最新 - 符合当前最佳实践
5. 示范性强 - 正确展示模式

收集时的警示信号

• 代码示例中有 TODO 或 FIXME
• 文件使用已弃用的模式
• 代码无法编译或运行
• 示例过于简单（< 10 行）
• 示例过于复杂（> 100 行）
• 没有针对该模式的测试

边缘情况

没有现有代码库

如果用户没有现有代码库：

I notice you don't have an existing codebase. Would you like to:

1. Skip style anchor collection for now (can add later)
2. Reference external examples (Effect documentation, framework examples)
3. Create minimal example files as anchors

Which approach works best for your project?

用户跳过所有类别

No style anchors collected. This means:

⚠️  Implementation-planner will generate tasks WITHOUT concrete examples
⚠️  Risk of architectural drift increases
⚠️  Developers will need to infer patterns from requirements

Recommendation: Collect at least 1-2 anchors for critical patterns
(e.g., service pattern, test pattern)

Continue without anchors? (yes/no)

文件无法访问

如果用户提供的文件路径无法读取：

I can't access [file-path]. Would you like to:

1. Provide a different file path
2. Paste the code directly (I'll store it in the anchor)
3. Provide a URL to the file
4. Skip this anchor

Your choice:

与 Implementation Planner 集成

运行 implementation-planner 时：

1. 加载风格锚点：

   Read {base_directory}/artifacts/style-anchors/index.yaml
   

2. 针对生成的每项任务：

   • 确定任务类型和文件模式
   • 查询 usage_matrix，获取推荐的锚点
   • 根据 applies_to 规则筛选锚点
   • 在任务说明中加入排名最高的 2-3 个相关锚点

3. 任务说明模板：

   instructions: |
     ## Style Anchors
     Follow these patterns:
     - `[anchor-id]` ([file]) - [what it demonstrates]
     - `[anchor-id]` ([file]) - [what it demonstrates]
   
     See artifacts/style-anchors/[anchor-id].md for detailed examples.
   
     ## [rest of task instructions]
   

验证

生成后，验证以下内容：

• index.yaml 是有效的 YAML
• 所有锚点 ID 都是唯一的
• 所有类别引用都能解析
• 索引中锚点对应的所有 .md 文件都存在
• 所有 .md 文件的 frontmatter 都与 index.yaml 匹配
• 源代码行范围的格式有效
• usage matrix 引用的锚点有效
• 每个类别至少有 1 个锚点

用法

要收集风格锚点：

/style-anchors-collection [base-directory]

如果未提供目录，则通过检查当前目录中的 requirements/technical-requirements.yaml 来自动检测。

如果未找到，则提示用户：“你的需求文档位于何处？”

等待用户提供路径后再继续。将其存储为 base_directory。

该技能将：

1. 从 {base_directory}/requirements/technical-requirements.yaml 加载技术需求
2. 确定要收集的模式类别
3. 以交互方式为每个类别收集锚点
4. 在 {base_directory}/artifacts/style-anchors/ 中生成 index.yaml
5. 为每个锚点生成单独的 .md 文件
6. 显示收集摘要

示例

示例锚点文档请参阅 references/example.md。