Back to Details

linear-implement

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Linear Issue Implementation

Linear Issue 实现流程

Overview

概述

This skill provides a comprehensive workflow for implementing Linear issues with professional software engineering practices. It automates the entire development lifecycle from issue analysis through PR creation, ensuring quality through test-driven development, parallel code reviews, and systematic validation.
本Skill提供一套遵循专业软件工程实践的Linear Issue完整实现工作流，可自动化从需求分析到PR创建的全开发生命周期，通过测试驱动开发、并行代码审查和系统化验证保障交付质量。

When to Use This Skill

适用场景

Use this skill when:
  • User provides a Linear issue ID (format: 
    TRA-9
    , 
    DEV-123
    , etc.)
  • User requests implementation of a Linear issue
  • User wants a structured TDD approach with code review
  • User needs automated workflow from issue to PR
Examples:
  • "Implement TRA-142"
  • "Help me build the feature in DEV-89"
  • "Work on Linear issue ABC-456"
在以下场景使用本Skill：
  • 用户提供Linear需求单ID（格式：
    TRA-9
    、
    DEV-123
    等）
  • 用户请求实现某Linear Issue功能
  • 用户需要结构化的TDD开发方案及代码审查
  • 用户需要从需求单到PR的自动化工作流
示例：
  • "实现TRA-142"
  • "帮我开发DEV-89中的功能"
  • "处理Linear Issue ABC-456"

Core Workflow

核心工作流

The skill follows a 14-step process:
  1. Fetch Linear Issue - Retrieve complete issue details via Linear MCP
  2. Gather Additional Context - Search Obsidian, Sentry, and GitHub for related information
  3. Move to In Progress - Update issue status to indicate active work
  4. Create Feature Branch - Use Linear's suggested git branch naming
  5. Analyze & Plan - Break down requirements and create implementation plan
  6. Save to Memory - Store plan in memory graph for tracking
  7. Review Plan - Present plan for user confirmation
  8. TDD Implementation - Invoke 
    tdd-workflow
    skill for test-driven development
  9. Parallel Code Reviews - Invoke 
    parallel-code-review
    skill for comprehensive analysis
  10. Address Feedback - Invoke 
    code-review-implementer
    skill to systematically fix issues
  11. Validation - Ensure all tests and linters pass
  12. Logical Commits - Create meaningful commit history
  13. Create PR - Generate comprehensive pull request with Linear linking
  14. Final Verification - Confirm CI/CD pipeline and Linear integration
本Skill遵循14步流程：
  1. 获取Linear Issue详情 - 通过Linear MCP获取完整需求单信息
  2. 收集额外上下文 - 从Obsidian、Sentry和GitHub搜索相关资料
  3. 标记为进行中 - 更新需求单状态以标识开发已启动
  4. 创建功能分支 - 使用Linear建议的Git分支命名规则
  5. 分析与规划 - 拆解需求并制定实现方案
  6. 保存至内存 - 将方案存储到内存图谱中以便跟踪
  7. 方案评审 - 向用户展示方案并确认
  8. TDD开发实现 - 调用
    tdd-workflow
    Skill执行测试驱动开发
  9. 并行代码审查 - 调用
    parallel-code-review
    Skill进行全面分析
  10. 处理反馈 - 调用
    code-review-implementer
    Skill系统化修复问题
  11. 验证 - 确保所有测试与代码检查工具通过
  12. 提交逻辑化代码 - 创建有意义的提交历史
  13. 创建PR - 生成包含Linear关联的完整拉取请求
  14. 最终验证 - 确认CI/CD流水线与Linear集成正常

Workflow Implementation Details

工作流实现细节

Step 1: Fetch Linear Issue Details

步骤1：获取Linear Issue详情

Retrieve the complete issue using Linear MCP tools:
mcp__linear__get_issue(id: <issue-id>)
Extract key information:
  • Title and description
  • Current status and priority
  • Suggested git branch name (
    branchName
    field)
  • Team and project context
  • Attachments or related work
  • Labels and assigned team members
通过Linear MCP工具获取完整需求单：
mcp__linear__get_issue(id: <issue-id>)
提取关键信息：
  • 标题与描述
  • 当前状态与优先级
  • 建议的Git分支名称（
    branchName
    字段）
  • 团队与项目上下文
  • 附件或相关工作
  • 标签与指派成员

Step 2: Gather Additional Context

步骤2：收集额外上下文

Before planning, gather related context from multiple sources to inform the implementation approach.
规划前，从多渠道收集相关上下文以指导实现方案。

Search Obsidian Vault

搜索Obsidian知识库

Search for any existing notes that might be related to this issue:
undefined
搜索与该需求单相关的现有笔记：
undefined

Search by issue ID

按需求单ID搜索

Search Obsidian vault for: "TRA-142"
在Obsidian知识库中搜索："TRA-142"

Search by issue summary/keywords

按需求单摘要/关键词搜索

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

Look for:
- Previous meeting notes discussing this feature
- Architecture decisions or technical notes
- Related implementation notes from similar work
- User research or requirements documentation
在Obsidian知识库中搜索："<需求单标题/描述中的关键词>"

重点查找：
- 之前讨论该功能的会议记录
- 架构决策或技术笔记
- 类似功能的相关实现文档
- 用户研究或需求文档

Fetch Sentry Context (if referenced)

获取Sentry上下文（若有引用）

If the Linear issue references any Sentry issues or error tracking:
mcp__sentry__get_issue(issue_id: <sentry-issue-id>)
Extract from Sentry:
  • Error stack traces and frequency
  • Affected users and environments
  • Related events and breadcrumbs
  • Any existing comments or assignments
This context helps understand:
  • The root cause of bugs
  • Which code paths are affected
  • How frequently the issue occurs
  • Environmental factors to consider
若Linear需求单引用了Sentry问题或错误追踪信息：
mcp__sentry__get_issue(issue_id: <sentry-issue-id>)
从Sentry提取：
  • 错误堆栈跟踪与发生频率
  • 受影响的用户与环境
  • 相关事件与操作轨迹
  • 现有评论或指派信息
这些上下文有助于理解：
  • 问题的根本原因
  • 受影响的代码路径
  • 问题发生的频率
  • 需要考虑的环境因素

Fetch GitHub Context (if referenced)

获取GitHub上下文（若有引用）

If the Linear issue references GitHub pull requests, issues, or discussions:
bash
undefined
若Linear需求单引用了GitHub拉取请求、问题或讨论：
bash
undefined

View PR details and discussion

查看PR详情与讨论

gh pr view <pr-number>
gh pr view <pr-number>

View PR comments and review threads

查看PR评论与评审线程

gh pr view <pr-number> --comments
gh pr view <pr-number> --comments

View issue details

查看Issue详情

gh issue view <issue-number>
gh issue view <issue-number>

View issue comments

查看Issue评论

gh issue view <issue-number> --comments

Extract from GitHub:
- Previous implementation attempts
- Review feedback and concerns raised
- Design discussions and decisions
- Related code changes or context

**Context Summary:**

After gathering context, summarize:
- Relevant information found in Obsidian
- Sentry error details (if applicable)
- GitHub discussion insights (if applicable)
- How this context affects the implementation approach
gh issue view <issue-number> --comments

从GitHub提取：
- 之前的实现尝试
- 评审反馈与提出的问题
- 设计讨论与决策
- 相关代码变更或上下文

**上下文总结：**

收集完上下文后，整理：
- 在Obsidian中找到的相关信息
- Sentry错误详情（若适用）
- GitHub讨论见解（若适用）
- 这些上下文对实现方案的影响

Step 3: Move Issue to In Progress

步骤3：将需求单标记为进行中

Update the issue status to reflect active development:
  1. Identify the team ID from the issue
  2. Retrieve "In Progress" state using 
    mcp__linear__list_issue_statuses(team: <team-id>)
  3. Update issue using 
    mcp__linear__update_issue(id: <issue-id>, state: <in-progress-state-id>)
This provides visibility to team members that work has begun.
更新需求单状态以反映开发进度：
  1. 从需求单中获取团队ID
  2. 使用
    mcp__linear__list_issue_statuses(team: <team-id>)
    获取“进行中”状态ID
  3. 使用
    mcp__linear__update_issue(id: <issue-id>, state: <in-progress-state-id>)
    更新状态
这能让团队成员清晰看到工作已启动。

Step 4: Create Feature Branch

步骤4：创建功能分支

Use Linear's suggested branch name for consistency:
bash
undefined
使用Linear建议的分支名称以保持一致性：
bash
undefined

Ensure on main and up-to-date

确保处于main分支且为最新版本

git checkout main git pull origin main
git checkout main git pull origin main

Get branch name from Linear's branchName field

从Linear的branchName字段获取分支名称

BRANCH_NAME="<from Linear branchName field>"
BRANCH_NAME="<来自Linear branchName字段>"

Create branch if new, or checkout if exists (idempotent)

若分支不存在则创建，否则切换到该分支（幂等操作）

git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"

Verify correct branch

验证当前分支是否正确

git branch --show-current

This pattern ensures:
- Reuse of existing branches
- Consistent Linear-suggested naming
- Idempotent operations (safe to re-run)
- Always working from latest main
git branch --show-current

该模式确保：
- 复用现有分支
- 遵循Linear建议的统一命名规则
- 幂等操作（可安全重复执行）
- 始终基于最新main分支开发

Step 5: Analyze and Plan Solution

步骤5：分析与规划解决方案

Break down the issue into an actionable implementation plan:
Analysis Process:
  1. Extract specific requirements from issue description
  2. Identify affected components and systems
  3. Determine testing strategy (unit → integration → system)
  4. Plan implementation approach following project patterns
  5. Identify potential risks and dependencies
Planning Output:
  • Goal: Clear statement of implementation objective
  • Requirements: Specific functional and technical requirements
  • Architecture: How solution fits existing codebase (models, services, controllers)
  • Test Strategy: Comprehensive testing including system specs
  • Implementation Steps: Ordered list of development tasks
  • Acceptance Criteria: Definition of done
将需求单拆解为可执行的实现方案：
分析流程：
  1. 从需求单描述中提取具体需求
  2. 识别受影响的组件与系统
  3. 确定测试策略（单元→集成→系统）
  4. 遵循项目模式规划实现方案
  5. 识别潜在风险与依赖
规划输出：
  • 目标：明确的实现目标陈述
  • 需求：具体的功能与技术要求
  • 架构：解决方案如何适配现有代码库（模型、服务、控制器）
  • 测试策略：包含系统测试的全面测试方案
  • 实现步骤：有序的开发任务列表
  • 验收标准：完成定义

Step 6: Save Plan to Memory

步骤6：将方案保存至内存

Store the implementation plan using memory MCP tools:
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"
    ]
  }
])
This creates permanent tracking of:
  • Issue context and requirements
  • Implementation approach and reasoning
  • Progress throughout development
  • Lessons learned for future work
使用内存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"
    ]
  }
])
这可永久跟踪：
  • 需求单上下文与需求
  • 实现方案与决策依据
  • 开发全程进度
  • 可供未来参考的经验教训

Step 7: Review Plan with User

步骤7：与用户评审方案

Present the complete plan for confirmation:
Plan Presentation:
  • Summary of what will be implemented
  • Key technical decisions and rationale
  • Testing strategy and expected coverage
  • Estimated complexity and identified risks
  • Explicit confirmation request
User Options:
  • Approve to proceed with implementation
  • Request modifications to approach
  • Add requirements or constraints
  • Ask clarifying questions
向用户展示完整方案并确认：
方案展示内容：
  • 实现内容摘要
  • 关键技术决策与理由
  • 测试策略与预期覆盖率
  • 预估复杂度与已识别风险
  • 明确的确认请求
用户选项：
  • 批准并推进实现
  • 请求修改方案
  • 添加需求或约束
  • 提出澄清问题

Step 8: Test-Driven Development Implementation

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

Upon approval, invoke the TDD workflow skill:
Invoke the Skill tool with: tdd-workflow
The TDD workflow skill enforces:
  • Red-Green-Refactor cycles
  • Test pyramid strategy (unit → integration → system)
  • Writing tests before implementation
  • Comprehensive test coverage including system specs
Expected Outcomes:
  • Complete test coverage for new functionality
  • Implementation following project POODR principles
  • Result pattern for operations that can fail
  • Clean, maintainable code structure
获得批准后，调用TDD工作流Skill：
通过Skill工具调用：tdd-workflow
TDD工作流Skill强制要求：
  • 红-绿-重构循环
  • 测试金字塔策略（单元→集成→系统）
  • 先写测试再实现代码
  • 包含系统测试的全面测试覆盖
预期成果：
  • 新功能的完整测试覆盖
  • 遵循项目POODR原则的实现
  • 针对可能失败操作的Result模式
  • 清晰、可维护的代码结构

Step 9: Parallel Subagent Code Reviews

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

After implementation, invoke the parallel code review skill:
Invoke the Skill tool with: parallel-code-review
This launches specialized review subagents in parallel:
Security Review:
  • OWASP Top 10 vulnerabilities
  • Multi-tenant security (ActsAsTenant verification)
  • XSS, CSRF, SQL injection prevention
  • Authentication and authorization checks
  • Sensitive data handling
Rails Best Practices Review:
  • POODR principles (SRP, dependency management, Tell Don't Ask)
  • Rails 7+ conventions
  • N+1 query prevention
  • ActiveRecord optimization
  • Service object patterns
  • Result pattern usage
Frontend Review (if applicable):
  • ViewComponent best practices
  • Tailwind CSS conventions
  • StimulusJS patterns
  • Accessibility (ARIA attributes)
Output:
  • Consolidated review report
  • Decision tracking to prevent redundancy
  • Prioritized feedback by severity and impact
实现完成后，调用并行代码审查Skill：
通过Skill工具调用：parallel-code-review
该Skill会并行启动专业评审子Agent：
安全评审：
  • OWASP Top 10漏洞检查
  • 多租户安全（ActsAsTenant验证）
  • XSS、CSRF、SQL注入防护
  • 认证与授权检查
  • 敏感数据处理
Rails最佳实践评审：
  • POODR原则（单一职责、依赖管理、Tell Don't Ask）
  • Rails 7+规范
  • N+1查询预防
  • ActiveRecord优化
  • 服务对象模式
  • Result模式使用
前端评审（若适用）：
  • ViewComponent最佳实践
  • Tailwind CSS规范
  • StimulusJS模式
  • 可访问性（ARIA属性）
输出：
  • 整合后的评审报告
  • 决策跟踪以避免重复
  • 按严重性与影响优先级排序的反馈

Step 10: Address Review Feedback

步骤10：处理评审反馈

Invoke the code review implementer skill:
Invoke the Skill tool with: code-review-implementer
This skill systematically addresses feedback:
Process:
  1. Parse and prioritize feedback by impact and effort
  2. Identify common refactoring patterns
  3. Implement fixes incrementally with test validation
  4. Ensure backward compatibility
  5. Update documentation as needed
Architectural Feedback is MANDATORY:
  • Extract service objects if controllers/models have too many responsibilities
  • Apply Result pattern for operations that can fail
  • Refactor to improve testability and maintainability
  • Add comprehensive specs for new service objects
Note: Do NOT create PR until all architectural feedback is implemented.
调用代码审查整改Skill：
通过Skill工具调用：code-review-implementer
该Skill会系统化处理反馈：
流程：
  1. 按影响与工作量解析并优先级排序反馈
  2. 识别常见重构模式
  3. 增量实现修复并通过测试验证
  4. 确保向后兼容性
  5. 按需更新文档
架构反馈为强制要求：
  • 若控制器/模型职责过多，提取为服务对象
  • 对可能失败的操作应用Result模式
  • 重构以提升可测试性与可维护性
  • 为新服务对象添加全面测试
注意： 在所有架构反馈处理完成前，请勿创建PR。

Step 11: Validation and Quality Assurance

步骤11：验证与质量保证

Before creating commits, ensure everything passes:
Validation Steps:
bash
undefined
创建提交前，确保所有检查通过：
验证步骤：
bash
undefined

Run full test suite

运行完整测试套件

bundle exec rspec
bundle exec rspec

Run linting (Standard, ERB, Brakeman)

运行代码检查（Standard、ERB、Brakeman）

bin/lint
bin/lint

Fix any failures or warnings

修复所有失败或警告

Verify system specs pass in clean environment

在干净环境中验证系统测试通过


**Quality Checks:**
- Code follows project POODR principles
- Result pattern used appropriately
- No security vulnerabilities
- Performance impact considered (no N+1 queries)
- All subagent feedback addressed
- Test coverage sufficient

**Linting Notes:**
- Yarn failures can be ignored if only working on Rails code
- Warnings about `MigratedSchemaVersion` and `ContextCreatingMethods` are harmless
- **Actual offenses must be addressed** (look for file paths and line numbers)

**质量检查：**
- 代码遵循项目POODR原则
- Result模式使用恰当
- 无安全漏洞
- 考虑性能影响（无N+1查询）
- 所有子Agent反馈已处理
- 测试覆盖率充足

**代码检查注意事项：**
- 若仅开发Rails代码，可忽略Yarn失败
- 关于`MigratedSchemaVersion`与`ContextCreatingMethods`的警告无害
- **必须处理实际违规问题**（查看文件路径与行号）

Step 12: Create Logical Commits

步骤12：创建逻辑化提交

Create meaningful commits that tell the implementation story:
Commit Strategy:
  1. Test commits: Add failing tests for new functionality
  2. Implementation commits: Add code to make tests pass
  3. Refactor commits: Improve code structure
  4. Security fixes: Address security review feedback
  5. Pattern improvements: Implement OOP/Rails pattern suggestions
  6. Documentation commits: Update docs if needed
Commit Message Format:
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
Use heredoc for proper formatting:
bash
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
)"
创建有意义的提交，清晰展现实现过程：
提交策略：
  1. 测试提交：添加新功能的失败测试
  2. 实现提交：添加代码使测试通过
  3. 重构提交：优化代码结构
  4. 安全修复：处理安全评审反馈
  5. 模式优化：实现OOP/Rails模式建议
  6. 文档提交：按需更新文档
提交消息格式：
50字符以内的现在时摘要

- 如有需要，添加详细说明（每行不超过72字符）
- 说明解决了哪条评审反馈
- 注明任何破坏性变更或迁移要求

Linear issue: <Linear issue URL>
Implemented with Claude Code
使用heredoc保证格式正确：
bash
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
)"

Step 13: Create Pull Request

步骤13：创建拉取请求（PR）

Generate comprehensive PR with Linear integration:
PR Creation Command:
bash
gh pr create --title "<concise-title>" --body "$(cat <<'EOF'
生成包含Linear集成的完整PR：
PR创建命令：
bash
gh pr create --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
  • 安全评审发现与解决情况
  • Rails最佳实践评审发现与解决情况
  • 性能考虑事项处理情况

Breaking Changes

破坏性变更

[None or list any breaking changes]
[无或列出所有破坏性变更]

Linear Issue

Linear Issue

Closes <Linear issue URL>
Implemented with Claude Code following TDD methodology with parallel code reviews. EOF )"

**PR Description Includes:**
- Summary of implementation
- Technical approach and key decisions
- Testing strategy and coverage
- Code review findings and resolutions
- Security considerations addressed
- Breaking changes or migration notes
- Screenshots/demos if applicable

**Linear Integration:**
- Include `Closes <Linear-issue-URL>` in PR body
- Linear automatically links and updates issue status when PR merges
Closes <Linear issue URL>
使用Claude Code遵循TDD方法论并结合并行代码审查实现。 EOF )"

**PR描述包含：**
- 实现内容摘要
- 技术方案与关键决策
- 测试策略与覆盖率
- 代码审查发现与解决情况
- 安全考虑事项处理情况
- 破坏性变更或迁移说明
- 截图/演示（若适用）

**Linear集成：**
- 在PR正文中包含`Closes <Linear-issue-URL>`
- 当PR合并时，Linear会自动关联并更新需求单状态

Step 14: Final Verification

步骤14：最终验证

Verify PR setup and completion:
Final Checks:
  • ✅ CI/CD pipeline triggered successfully
  • ✅ Linear issue linked and updated
  • ✅ All tests passing in CI environment
  • ✅ Code review assignees notified
  • ✅ Branch protection rules satisfied
  • ✅ Security and pattern reviews documented
Completion Summary: Present checklist to user:
  • ✅ Linear issue analyzed and planned
  • ✅ Solution implemented with TDD
  • ✅ Comprehensive system specs added
  • ✅ Security review completed
  • ✅ Rails/OOP patterns review completed
  • ✅ All review feedback addressed
  • ✅ All tests and linting pass
  • ✅ Logical commit history created
  • ✅ PR created with Linear integration
验证PR设置与完成情况：
最终检查项：
  • ✅ CI/CD流水线已成功触发
  • ✅ Linear需求单已关联并更新
  • ✅ CI环境中所有测试通过
  • ✅ 已通知代码审查指派人员
  • ✅ 满足分支保护规则
  • ✅ 已记录安全与模式评审情况
完成总结： 向用户展示完成清单：
  • ✅ Linear需求单已分析与规划
  • ✅ 采用TDD完成解决方案实现
  • ✅ 添加了全面的系统测试
  • ✅ 已完成安全评审
  • ✅ 已完成Rails/OOP模式评审
  • ✅ 所有评审反馈已处理
  • ✅ 所有测试与代码检查通过
  • ✅ 创建了逻辑化提交历史
  • ✅ 创建了集成Linear的PR

Integration with Other Skills

与其他Skill的集成

This skill orchestrates multiple specialized skills:
tdd-workflow:
  • Enforces Red-Green-Refactor cycles
  • Ensures test-first development
  • Guides test pyramid strategy
parallel-code-review:
  • Runs security and Rails reviews concurrently
  • Consolidates findings to avoid redundancy
  • Provides prioritized feedback
code-review-implementer:
  • Systematically addresses all feedback
  • Applies common refactoring patterns
  • Validates fixes with tests
本Skill协调多个专业Skill：
tdd-workflow：
  • 强制红-绿-重构循环
  • 确保测试优先开发
  • 指导测试金字塔策略
parallel-code-review：
  • 同时运行安全与Rails评审
  • 整合发现以避免重复
  • 提供优先级排序的反馈
code-review-implementer：
  • 系统化处理所有反馈
  • 应用常见重构模式
  • 通过测试验证修复

Project-Specific Conventions

项目特定规范

This skill adheres to project guidelines from 
CLAUDE.md
:
Rails Patterns:
  • Service objects for business logic
  • Result pattern for operations that can fail
  • POODR principles (SRP, Tell Don't Ask, Law of Demeter)
Multi-Tenant Security:
  • ActsAsTenant automatic scoping
  • Tenant isolation verification
  • No need for explicit tenant scoping in queries
Testing:
  • RSpec with shoulda-matchers
  • System specs for user workflows
  • Avoid stubbing the system under test
  • Use backdoor middleware for auth in request specs
Code Style:
  • i18n for all user-facing text
  • Timestamp columns instead of booleans
  • Postgres enums for static values
  • ENV.fetch
    for required environment variables
本Skill遵循
CLAUDE.md
中的项目指南：
Rails模式：
  • 业务逻辑使用服务对象
  • 可能失败的操作使用Result模式
  • POODR原则（单一职责、Tell Don't Ask、迪米特法则）
多租户安全：
  • ActsAsTenant自动作用域
  • 租户隔离验证
  • 查询中无需显式指定租户作用域
测试：
  • 使用RSpec与shoulda-matchers
  • 系统测试覆盖用户工作流
  • 避免存根被测系统
  • 在请求测试中使用后门中间件进行认证
代码风格：
  • 所有用户可见文本使用i18n
  • 使用时间戳列而非布尔值
  • 静态值使用Postgres枚举
  • 必需环境变量使用
    ENV.fetch

Requirements

要求

Linear MCP Integration:
  • Linear MCP server must be configured and available
  • Required tools: 
    mcp__linear__get_issue
    , 
    mcp__linear__update_issue
    , etc.
Git Repository:
  • Current directory must be a git repository
  • main
    branch exists and is up-to-date
  • Git configured with user credentials
Testing and Linting:
  • bundle exec rspec
    available for testing
  • bin/lint
    script available for linting
  • Ruby/Rails development environment configured
GitHub CLI:
  • gh
    CLI tool installed and authenticated
  • Repository configured for PR creation
Skills:
  • tdd-workflow
    skill available
  • parallel-code-review
    skill available
  • code-review-implementer
    skill available
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创建权限
Skills：
  • tdd-workflow
    Skill可用
  • parallel-code-review
    Skill可用
  • code-review-implementer
    Skill可用

Error Handling

错误处理

Common Issues and Solutions:
Linear Issue Not Found:
  • Verify issue ID format (e.g., 
    TRA-9
    , not 
    tra-9
    )
  • Confirm Linear MCP integration is working
  • Check user has access to the team/issue
Branch Already Exists:
  • Expected behavior - workflow checks out existing branch
  • Ensures work can be resumed safely
  • Verifies branch is synced with remote
Tests or Linting Fail:
  • Review failures and fix before creating PR
  • Common linting issues: StandardRB, ERB Lint, Brakeman
  • Never use 
    standardrb --fix
    blindly - review changes
Code Review Identifies Issues:
  • MUST address architectural feedback before PR
  • Extract service objects as recommended
  • Apply Result pattern where suggested
  • Only create PR after all feedback implemented
常见问题与解决方案：
Linear Issue未找到：
  • 验证需求单ID格式（例如
    TRA-9
    ，而非
    tra-9
    ）
  • 确认Linear MCP集成正常
  • 检查用户是否有权限访问该团队/需求单
分支已存在：
  • 预期行为 - 工作流会切换到现有分支
  • 确保可安全恢复工作
  • 验证分支已与远程同步
测试或代码检查失败：
  • 查看失败原因并在创建PR前修复
  • 常见代码检查问题：StandardRB、ERB Lint、Brakeman
  • 不要盲目使用
    standardrb --fix
    - 需先查看变更内容
代码审查发现问题：
  • 创建PR前必须处理所有架构反馈
  • 按建议提取服务对象
  • 按建议应用Result模式
  • 仅在所有反馈处理完成后创建PR

Example Workflow

示例工作流

User Request:
Implement TRA-142
Skill Response:
  1. Fetches TRA-142 from Linear
  2. Gathers additional context:
    • Searches Obsidian vault for "TRA-142" and related keywords
    • Fetches Sentry issue details (if referenced in Linear issue)
    • Retrieves GitHub PR discussions (if referenced in Linear issue)
  3. Updates issue to "In Progress"
  4. Creates branch 
    dg/tra-142-user-notification-service
  5. Analyzes requirements and creates plan (informed by gathered context)
  6. Saves plan to memory graph
  7. Presents plan: "This will create a new service object for user notifications using the Result pattern..."
  8. Waits for user approval
  9. Upon approval, invokes 
    tdd-workflow
    skill
  10. After implementation, invokes 
    parallel-code-review
    skill
  11. Reviews identify: "Extract notification logic to service object, apply Result pattern"
  12. Invokes 
    code-review-implementer
    skill to address feedback
  13. Runs validation: 
    bundle exec rspec
    ✅, 
    bin/lint
    ✅
  14. Creates logical commits with proper messages
  15. Creates PR with comprehensive description and Linear linking
  16. Presents completion checklist
Final Output:
  • Working feature branch with complete implementation
  • All tests passing
  • All linting passing
  • Comprehensive PR with Linear integration
  • Issue automatically updated when PR merges
用户请求：
实现TRA-142
Skill响应：
  1. 从Linear获取TRA-142详情
  2. 收集额外上下文：
    • 在Obsidian知识库中搜索"TRA-142"及相关关键词
    • 获取Sentry问题详情（若Linear需求单中有引用）
    • 获取GitHub PR讨论（若Linear需求单中有引用）
  3. 将需求单更新为“进行中”
  4. 创建分支
    dg/tra-142-user-notification-service
  5. 分析需求并制定方案（结合收集到的上下文）
  6. 将方案保存到内存图谱
  7. 展示方案：“将使用Result模式创建新的用户通知服务对象...”
  8. 等待用户批准
  9. 获得批准后，调用
    tdd-workflow
    Skill
  10. 实现完成后，调用
    parallel-code-review
    Skill
  11. 评审发现：“将通知逻辑提取到服务对象，应用Result模式”
  12. 调用
    code-review-implementer
    Skill处理反馈
  13. 运行验证：
    bundle exec rspec
    ✅，
    bin/lint
    ✅
  14. 创建格式规范的逻辑化提交
  15. 创建包含完整描述与Linear关联的PR
  16. 展示完成清单
最终输出：
  • 包含完整实现的可用功能分支
  • 所有测试通过
  • 所有代码检查通过
  • 包含Linear集成的完整PR
  • PR合并时需求单会自动更新

Best Practices

最佳实践

Planning Phase:
  • Take time to understand requirements fully
  • Identify edge cases and error conditions
  • Consider multi-tenant implications
  • Plan for comprehensive system specs
Implementation Phase:
  • Follow TDD strictly - tests before code
  • Keep commits small and logical
  • Write self-documenting code
  • Use i18n for all user-facing text
Review Phase:
  • Address ALL architectural feedback
  • Don't skip recommended refactoring
  • Validate fixes with tests
  • Consider performance implications
PR Creation:
  • Write comprehensive descriptions
  • Document review findings and resolutions
  • Include manual testing notes
  • Ensure Linear linking is correct
Quality Gates:
  • Never create PR with failing tests
  • Never create PR with linting errors
  • Never create PR without addressing architectural feedback
  • Never skip validation steps
规划阶段：
  • 花时间充分理解需求
  • 识别边缘情况与错误场景
  • 考虑多租户影响
  • 规划全面的系统测试
实现阶段：
  • 严格遵循TDD - 先写测试再写代码
  • 保持提交小而逻辑清晰
  • 编写自文档化代码
  • 所有用户可见文本使用i18n
评审阶段：
  • 处理所有架构反馈
  • 不要跳过建议的重构
  • 通过测试验证修复
  • 考虑性能影响
PR创建：
  • 编写完整的描述
  • 记录评审发现与解决情况
  • 包含手动测试说明
  • 确保Linear关联正确
质量门禁：
  • 测试失败时绝不创建PR
  • 代码检查错误时绝不创建PR
  • 未处理架构反馈时绝不创建PR
  • 绝不跳过验证步骤