linear-implement

Linear 问题实现

概述

此技能提供了一个全面的工作流，帮助你按照专业的软件工程实践实现 Linear 问题。它将从分析问题到创建 PR 的整个开发生命周期自动化，并通过测试驱动开发、并行代码审查和系统化验证来确保质量。

何时使用此技能

在以下情况下使用此技能：

• 用户提供了 Linear 问题 ID（格式：TRA-9、DEV-123 等）
• 用户请求实现一个 Linear 问题
• 用户希望采用结构化的 TDD 方法并进行代码审查
• 用户需要自动化的从问题到 PR 的工作流

示例：

• “实现 TRA-142”
• “帮我开发 DEV-89 中的功能”
• “处理 Linear 问题 ABC-456”

核心工作流

此技能遵循一个包含 14 个步骤的流程：

1. 获取 Linear 问题 - 通过 Linear MCP 获取完整的问题详情
2. 收集额外背景信息 - 搜索 Obsidian、Sentry 和 GitHub，查找相关信息
3. 移至进行中 - 更新问题状态以标记工作已开始
4. 创建功能分支 - 使用 Linear 建议的 git 分支命名
5. 分析并制定计划 - 分解需求并制定实现计划
6. 保存到记忆 - 将计划存储在记忆图中以便跟踪
7. 审查计划 - 提交计划供用户确认
8. TDD 实现 - 调用 tdd-workflow 技能进行测试驱动开发
9. 并行代码审查 - 调用 parallel-code-review 技能进行全面分析
10. 处理反馈 - 调用 code-review-implementer 技能，系统性地修复问题
11. 验证 - 确保所有测试和代码检查工具均通过
12. 逻辑性提交 - 创建有意义的提交历史
13. 创建 PR - 创建包含 Linear 链接的完整拉取请求
14. 最终验证 - 确认 CI/CD 流水线和 Linear 集成正常

工作流实现详情

步骤 1：获取 Linear 问题详情

使用 Linear MCP 工具获取完整的问题信息：

mcp__linear__get_issue(id: <issue-id>)

提取关键信息：

• 标题和描述
• 当前状态和优先级
• 建议的 git 分支名称（branchName 字段）
• 团队和项目背景
• 附件或相关工作
• 标签和受指派的团队成员

步骤 2：收集额外背景信息

制定计划前，从多个来源收集相关背景信息，以指导实现方案。

搜索 Obsidian Vault

搜索可能与此问题相关的现有笔记：

# Search by issue ID
Search Obsidian vault for: "TRA-142"

# Search by issue summary/keywords
Search Obsidian vault for: "<keywords from issue title/description>"

查找：

• 讨论此功能的过往会议记录
• 架构决策或技术笔记
• 类似工作的相关实现笔记
• 用户研究或需求文档

获取 Sentry 背景信息（如有引用）

如果 Linear 问题引用了任何 Sentry 问题或错误跟踪信息：

mcp__sentry__get_issue(issue_id: <sentry-issue-id>)

从 Sentry 提取：

• 错误堆栈跟踪和发生频率
• 受影响的用户和环境
• 相关事件和面包屑
• 现有评论或指派信息

这些背景信息有助于了解：

• Bug 的根本原因
• 受影响的代码路径
• 问题发生的频率
• 需要考虑的环境因素

获取 GitHub 背景信息（如有引用）

如果 Linear 问题引用了 GitHub 拉取请求、问题或讨论：

# View PR details and discussion
gh pr view <pr-number>

# View PR comments and review threads
gh pr view <pr-number> --comments

# View issue details
gh issue view <issue-number>

# View issue comments
gh issue view <issue-number> --comments

从 GitHub 提取：

• 之前的实现尝试
• 审查反馈和提出的疑虑
• 设计讨论和决策
• 相关代码更改或背景信息

背景信息摘要：

收集背景信息后，总结：

• 在 Obsidian 中找到的相关信息
• Sentry 错误详情（如适用）
• GitHub 讨论中的见解（如适用）
• 这些背景信息对实现方案的影响

第 3 步：将 Issue 移至进行中

更新 Issue 状态，以反映开发工作已开始：

1. 从 Issue 中识别团队 ID
2. 使用 mcp__linear__list_issue_statuses(team: <team-id>) 获取“进行中”状态
3. 使用 mcp__linear__update_issue(id: <issue-id>, state: <in-progress-state-id>) 更新 Issue

这样团队成员就能看到工作已开始。

第 4 步：创建功能分支

使用 Linear 建议的分支名称，以保持一致：

# Ensure on main and up-to-date
git checkout main
git pull origin main

# Get branch name from Linear's branchName field
BRANCH_NAME="<from Linear branchName field>"

# Create branch if new, or checkout if exists (idempotent)
git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"

# Verify correct branch
git branch --show-current

此模式可确保：

• 重用现有分支
• 遵循 Linear 建议的统一命名
• 操作具有幂等性（可安全地重新运行）
• 始终基于最新的 main 开展工作

第 5 步：分析并规划解决方案

将 Issue 拆解为可执行的实现计划：

分析流程：

1. 从 Issue 描述中提取具体要求
2. 确定受影响的组件和系统
3. 确定测试策略（单元 → 集成 → 系统）
4. 遵循项目模式规划实现方案
5. 识别潜在风险和依赖项

规划输出：

• 目标：清晰说明实现目标
• 要求：具体的功能和技术要求
• 架构：解决方案如何融入现有代码库（模型、服务、控制器）
• 测试策略：全面的测试，包括系统规格测试
• 实现步骤：按顺序列出开发任务
• 验收标准：完成定义

第 6 步：将计划保存到记忆中

使用 memory MCP 工具存储实现计划：

mcp__memory__create_entities(entities: [
  {
    name: "Linear Issue <issue-id>",
    entityType: "implementation-plan",
    observations: [
      "Requirements: <requirements>",
      "Architecture: <architecture-decisions>",
      "Test Strategy: <test-approach>",
      "Status: planning-complete"
    ]
  }
])

这会永久记录：

• Issue 上下文和要求
• 实现方案和理由
• 开发过程中的进度
• 供未来工作参考的经验教训

第 7 步：与用户审查计划

提交完整计划以供确认：

计划展示内容：

• 将要实现内容的摘要
• 关键技术决策及理由
• 测试策略和预期覆盖范围
• 预估复杂度和已识别的风险
• 明确请求确认

用户选项：

• 批准并继续实现
• 请求修改方案
• 添加要求或约束
• 提出澄清性问题

第 8 步：测试驱动开发实现

获得批准后，调用 TDD 工作流技能：

Invoke the Skill tool with: tdd-workflow

TDD 工作流技能要求遵循：

• Red-Green-Refactor 循环
• 测试金字塔策略（单元 → 集成 → 系统）
• 先编写测试，再进行实现
• 全面的测试覆盖，包括系统规格测试

预期结果：

• 新功能具备完整的测试覆盖
• 实现遵循项目的 POODR 原则
• 对可能失败的操作使用 Result 模式
• 代码结构整洁、易于维护

第 9 步：并行子 Agent 代码审查

实现完成后，调用并行代码审查技能：

Invoke the Skill tool with: parallel-code-review

该技能会并行启动专门的审查子 Agent：

安全审查：

• OWASP Top 10 漏洞
• 多租户安全性（验证 ActsAsTenant）
• XSS、CSRF、SQL 注入防护
• 身份验证和授权检查
• 敏感数据处理

Rails 最佳实践审查：

• POODR 原则（SRP、依赖管理、Tell Don't Ask）
• Rails 7+ 约定
• 防止 N+1 查询
• ActiveRecord 优化
• 服务对象模式
• Result 模式的使用

前端审查（如适用）：

• ViewComponent 最佳实践
• Tailwind CSS 约定
• StimulusJS 模式
• 无障碍功能（ARIA 属性）

输出：

• 汇总的审查报告
• 决策跟踪，避免重复审查
• 根据严重程度和影响对反馈进行优先级排序

步骤 10：处理审查反馈

调用代码审查实施技能：

Invoke the Skill tool with: code-review-implementer

此技能会系统地处理反馈：

流程：

1. 按影响和工作量解析反馈并确定优先级
2. 找出常见的重构模式
3. 逐步实施修复，并通过测试验证
4. 确保向后兼容
5. 根据需要更新文档

架构反馈为强制要求：

• 如果控制器／模型职责过多，则提取服务对象
• 对可能失败的操作采用 Result 模式
• 重构以提升可测试性和可维护性
• 为新的服务对象添加全面的规格测试

注意： 实施完所有架构反馈前，切勿创建 PR。

步骤 11：验证与质量保证

创建提交前，确保所有检查均通过：

验证步骤：

# Run full test suite
bundle exec rspec

# Run linting (Standard, ERB, Brakeman)
bin/lint

# Fix any failures or warnings
# Verify system specs pass in clean environment

质量检查：

• 代码遵循项目的 POODR 原则
• 适当使用 Result 模式
• 不存在安全漏洞
• 已考虑性能影响（无 N+1 查询）
• 已处理所有子 Agent 的反馈
• 测试覆盖率充足

Lint 说明：

• 如果只处理 Rails 代码，可以忽略 Yarn 失败
• 有关 MigratedSchemaVersion 和 ContextCreatingMethods 的警告无害
• 必须处理实际违规项（查看文件路径和行号）

步骤 12：创建逻辑清晰的提交

创建有意义的提交，清晰呈现实现过程：

提交策略：

1. 测试提交：为新功能添加失败测试
2. 实现提交：添加代码以通过测试
3. 重构提交：改进代码结构
4. 安全修复：处理安全审查反馈
5. 模式改进：实施 OOP／Rails 模式建议
6. 文档提交：根据需要更新文档

提交消息格式：

Present-tense summary under 50 characters

- Detailed explanation if needed (under 72 chars per line)
- Reference which review feedback was addressed
- Note any breaking changes or migration requirements

Linear issue: <Linear issue URL>
Implemented with Claude Code

使用 heredoc 确保格式正确：

git commit -m "$(cat <<'EOF'
Add user notification service

- Extract notification logic from controller
- Apply Result pattern for error handling
- Add comprehensive RSpec tests with edge cases

Linear issue: https://linear.app/company/issue/TRA-142
Implemented with Claude Code
EOF
)"

步骤 13：创建拉取请求

创建包含 Linear 集成信息的完整 PR：

PR 创建命令：

gh pr create --title "<concise-title>" --body "$(cat <<'EOF'
## Summary
- Concise bullet points of what was implemented
- Key technical decisions made

## Implementation Details
- Architecture approach and patterns used
- Services/models/controllers added or modified
- Database changes (if applicable)

## Testing Strategy
- Test coverage added (unit, integration, system)
- Edge cases covered
- Manual testing performed

## Code Review Process
- Security review findings and resolutions
- Rails best practices review findings and resolutions
- Performance considerations addressed

## Breaking Changes
[None or list any breaking changes]

## Linear Issue
Closes <Linear issue URL>

---
Implemented with Claude Code following TDD methodology with parallel code reviews.
EOF
)"

PR 描述包括：

• 实现概要
• 技术方案和关键决策
• 测试策略和覆盖情况
• 代码审查发现及处理结果
• 已处理的安全考量
• 破坏性变更或迁移说明
• 适用时附上截图／演示

Linear 集成：

• 在 PR 正文中包含 Closes <Linear-issue-URL>
• PR 合并后，Linear 会自动关联并更新问题状态

步骤 14：最终验证

验证 PR 配置和完成情况：

最终检查：

• ✅ CI/CD 流水线已成功触发
• ✅ 已关联 Linear 问题并更新状态
• ✅ CI 环境中的所有测试均已通过
• ✅ 已通知代码审查负责人
• ✅ 已满足分支保护规则
• ✅ 已记录安全审查和模式审查

完成摘要： 向用户展示检查清单：

• ✅ 已分析并规划 Linear 问题
• ✅ 已通过 TDD 实施解决方案
• ✅ 已添加全面的系统规格测试
• ✅ 已完成安全审查
• ✅ 已完成 Rails/OOP 模式审查
• ✅ 已处理所有审查反馈
• ✅ 所有测试和 lint 检查均已通过
• ✅ 已创建逻辑清晰的提交历史
• ✅ 已创建集成 Linear 的 PR

与其他技能的集成

此技能会协调多种专用技能：

tdd-workflow：

• 强制执行 Red-Green-Refactor 循环
• 确保先编写测试再开发
• 指导测试金字塔策略

parallel-code-review：

• 并行执行安全审查和 Rails 审查
• 汇总发现，避免重复
• 提供按优先级排序的反馈

code-review-implementer：

• 系统地处理所有反馈
• 应用常见的重构模式
• 通过测试验证修复

项目专属约定

此技能遵循 CLAUDE.md 中的项目指南：

Rails 模式：

• 使用服务对象处理业务逻辑
• 对可能失败的操作采用 Result 模式
• 遵循 POODR 原则（SRP、Tell Don't Ask、Law of Demeter）

多租户安全：

• 使用 ActsAsTenant 自动限定作用范围
• 验证租户隔离
• 查询中无需显式限定租户范围

测试：

• 使用 RSpec 和 shoulda-matchers
• 使用系统规格测试用户工作流
• 避免对被测系统进行桩替换
• 在请求规格中使用后门中间件进行身份验证

代码风格：

• 所有面向用户的文本均使用 i18n
• 使用时间戳列，而非布尔值
• 静态值使用 Postgres 枚举
• 必需的环境变量使用 ENV.fetch

要求

Linear MCP 集成：

• 必须配置并启用 Linear MCP 服务
• 必需的工具：mcp__linear__get_issue、mcp__linear__update_issue 等

Git 仓库：

• 当前目录必须是 Git 仓库
• main 分支必须存在且为最新状态
• Git 必须配置好用户凭据

测试和代码检查：

• 可使用 bundle exec rspec 运行测试
• 可使用 bin/lint 脚本进行代码检查
• 已配置 Ruby/Rails 开发环境

GitHub CLI：

• 已安装并完成身份验证的 gh CLI 工具
• 仓库已配置为可创建 PR

技能：

• 可使用 tdd-workflow 技能
• 可使用 parallel-code-review 技能
• 可使用 code-review-implementer 技能

错误处理

常见问题及解决方案：

未找到 Linear 问题：

• 验证问题 ID 格式（例如，使用 TRA-9，而非 tra-9）
• 确认 Linear MCP 集成正常运行
• 检查用户是否有权访问该团队/问题

分支已存在：

• 这是预期行为——工作流会检出已有分支
• 确保可以安全地恢复工作
• 验证分支已与远程同步

测试或代码检查失败：

• 检查失败原因，并在创建 PR 前修复
• 常见代码检查问题：StandardRB、ERB Lint、Brakeman
• 切勿盲目使用 standardrb --fix——应检查更改

代码审查发现问题：

• 创建 PR 前，必须处理架构方面的反馈
• 按建议提取服务对象
• 在建议的位置应用 Result 模式
• 只有在落实所有反馈后才能创建 PR

工作流示例

用户请求：

Implement TRA-142

技能响应：

1. 从 Linear 获取 TRA-142
2. 收集更多上下文：
   • 在 Obsidian 知识库中搜索“TRA-142”及相关关键词
   • 获取 Sentry 问题详情（如果 Linear 问题中有引用）
   • 获取 GitHub PR 讨论内容（如果 Linear 问题中有引用）
3. 将问题状态更新为“In Progress”
4. 创建分支 dg/tra-142-user-notification-service
5. 分析需求并制定计划（结合收集到的上下文）
6. 将计划保存到记忆图谱
7. 呈现计划：“这将使用 Result 模式为用户通知创建新的服务对象……”
8. 等待用户批准
9. 获得批准后，调用 tdd-workflow 技能
10. 实现完成后，调用 parallel-code-review 技能
11. 审查发现：“将通知逻辑提取到服务对象中，并应用 Result 模式”
12. 调用 code-review-implementer 技能处理反馈
13. 运行验证：bundle exec rspec ✅、bin/lint ✅
14. 创建带有恰当说明的逻辑提交
15. 创建包含详尽说明并关联 Linear 的 PR
16. 呈现完成检查清单

最终输出：

• 可用的功能分支，包含完整实现
• 所有测试均通过
• 所有代码检查均通过
• 与 Linear 集成的详尽 PR
• PR 合并后自动更新问题

最佳实践

规划阶段：

• 花时间全面了解需求
• 识别边缘情况和错误条件
• 考虑多租户影响
• 规划全面的系统规范

实现阶段：

• 严格遵循 TDD——先编写测试，再编写代码
• 保持提交小而合理
• 编写自说明代码
• 所有面向用户的文本都使用 i18n

审查阶段：

• 处理所有架构反馈
• 不要跳过建议的重构
• 通过测试验证修复
• 考虑性能影响

创建 PR：

• 撰写全面的说明
• 记录审查发现和解决方案
• 附上手动测试说明
• 确保 Linear 链接正确

质量门禁：

• 测试未通过时绝不创建 PR
• 存在 lint 错误时绝不创建 PR
• 未处理架构反馈时绝不创建 PR
• 绝不跳过验证步骤