mcpField
C
code-assist

code-assist

github.com/mikeyobrien开发3.2k49 次安装2 周前更新
代码仓库

关于 code-assist

Code Assist 是一项技能，通过 Explore、Plan、Code、Commit 流程和测试驱动开发指导代码实现。它支持交互协作或自主执行，并记录规划与进度文档。

主要功能

  1. 01从探索到提交的实现流程
  2. 02先编写测试并遵循 RED–GREEN–REFACTOR
  3. 03支持交互和自主模式
  4. 04记录规划、上下文、进度及构建日志

适用场景

  1. 01先编写测试再实现功能
  2. 02根据粗略任务描述制定计划
  3. 03遵循仓库指引和现有代码模式
  4. 04跟踪实现决策与验证结果

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mikeyobrien/ralph-orchestrator --skill code-assist

安装后在 Claude Code 中输入/code-assist确认已加载。

详细介绍

代码辅助

概述

在「探索、规划、编码、提交」工作流中，使用测试驱动开发指导代码任务的实现。在自动化与用户协作之间取得平衡，同时遵循现有的软件包模式，并优先考虑可读性和可扩展性。

参数

  • task_description（必填）：任务规范、粗略想法、.code-task.md 文件路径或 URL
  • additional_context（可选）：实现所需的补充背景信息
  • documentation_dir（可选，默认值：".sop/planning"）：规划文档目录
  • repo_root（可选，默认值：当前工作目录）：代码实现所在的仓库根目录
  • task_name（可选）：简短且具有描述性的名称（如未提供，则自动生成）
  • mode（可选，默认值："auto"）："interactive"（每个步骤都需确认）或 "auto"（自主执行）

约束：

  • 你必须在单个提示中一次性询问所有参数，以避免反复打断
  • 你必须验证输入：将模式规范化为 "interactive"/"auto"，验证路径，并在需要时生成 task_name

模式行为

在所有步骤中遵循以下模式：

交互模式： 提出操作并请求确认。如果有多种方案，说明各自的优缺点。提出澄清问题。在关键决策点暂停。提供有助于理解的背景信息。

自动模式： 自主执行。在 progress.md 中记录所有决策和推理。选择最合适的方案并说明原因。完成后提供全面总结。

重要说明

职责分离： 文档放在 {documentation_dir} 中。代码（测试和实现）放在 repo_root 中。绝不要混放。文档应以高层概念指导实现，而不是直接提供实现。文档中如需包含代码片段，应简短，并明确标注为示例或参考。

CODEASSIST.md 集成： 如果 repo_root 中存在 CODEASSIST.md，应阅读并在整个过程中遵循其中的约束。

步骤

1. 设置

初始化项目环境并创建所需的目录结构。

约束：

  • 你必须创建 {documentation_dir}/implementation/{task_name}/（包含 logs 子目录），并在继续之前确认其存在
  • 你必须查找指引文件（CODEASSIST.md、README.md、CONTRIBUTING.md、ARCHITECTURE.md 等），并在 context.md 中总结相关信息
  • 你必须创建 context.md（项目结构、需求、模式、依赖项）和 progress.md（使用 Markdown 清单跟踪执行进度）
  • 如果 task_description 指向带有 YAML 前置元数据的 .code-task.md，应将 status: in_progress 和 started: <date> 更新为对应值（如果尚未设置）

💬 有关模式特定的交互指导，请参阅 模式行为

2. 探索阶段
2.1 分析需求和背景信息

分析任务描述和现有文档，找出核心功能、边缘情况和约束。

约束：

  • 即使任务描述较为粗略，你也必须列出明确的功能需求和验收标准
  • 你必须确定适当的文件路径、语言，并确保与现有项目结构一致
  • 在交互模式下，与用户讨论需求、澄清歧义并确认你对需求的理解

💬 有关模式特定的交互指导，请参阅 模式行为

2.2 调研现有模式

搜索类似实现，并确定实现将交互的接口、库和组件。

约束：

  • 你必须在仓库中搜索相关代码、模式和惯例
  • 你必须创建依赖关系图，并在 context.md 中更新实现路径

💬 有关模式特定的交互指导，请参阅 模式行为

3. 规划阶段
3.1 设计测试策略

创建测试场景，涵盖正常操作、边缘情况和错误情况。

约束：

  • 你必须为每项验收标准至少覆盖一个测试场景
  • 你必须定义明确的输入/输出对，并将场景保存到 plan.md
  • 你必须设计出最初会失败的测试（设计阶段不得使用模拟实现）

💬 有关特定模式的交互指导，请参阅 Mode Behavior

3.2 实施规划与跟踪

概述高层结构并制定实施计划。

约束：

  • 你必须将包含关键实施任务的计划保存到 plan.md
  • 你必须使用 Markdown 复选框格式，在 progress.md 中维护实施清单
  • 在交互模式下，提供多种方案并列出优缺点，讨论其中的权衡

💬 有关特定模式的交互指导，请参阅 Mode Behavior

4. 代码阶段

阶段通用约束：

  • 你必须将所有代码（测试和实现）放在 repo_root 中，绝不能放在 documentation_dir 中
  • 你必须在进入下一子步骤前，确认测试/构建通过
  • 你必须遵循现有代码库的约定（命名、模式、错误处理、测试风格）
  • 将构建输出传入 {documentation_dir}/implementation/{task_name}/logs/，并搜索成功/失败标识
4.1 编写测试用例

严格遵循 TDD 原则编写测试用例。

约束：

  • 你必须在编写任何实现代码之前，为所有需求编写测试
  • 你必须执行测试以确认它们按预期失败，并记录失败原因
  • 你必须遵循现有代码库所使用的测试框架约定

💬 有关特定模式的交互指导，请参阅 Mode Behavior

4.2 编写实现代码

编写实现代码以通过测试，首先关注简洁性和正确性。

约束：

  • 你必须遵循 TDD 循环：RED → GREEN → REFACTOR
  • 你必须只实现通过当前测试所需的内容（YAGNI、KISS、SOLID）
  • 你必须在每个实现步骤后执行测试，以确认测试通过

💬 有关特定模式的交互指导，请参阅 Mode Behavior

4.3 重构与优化

检查实现，确保其简洁、完善并符合约定。

约束：

  • 你必须在开始前确认所有测试和构建均通过——先修复所有失败
  • 你必须使实现符合周边代码库的约定（命名、结构、错误处理、导入、日志记录）
  • 重构过程中必须始终保持测试通过

💬 有关特定模式的交互指导，请参阅 Mode Behavior

4.4 验证实现

确认实现完整且正确。

约束：

  • 你必须运行完整测试套件并执行构建，确认全部通过
  • 你必须确认实施计划中的所有事项均已完成
  • 只要仍有测试失败，你就不得宣称任务已完成

💬 有关特定模式的交互指导，请参阅 Mode Behavior

5. 提交阶段

拟定符合规范的提交信息并执行 git commit。

约束：

  • 只有确认构建和测试均通过后，才能提交
  • 你必须遵循 Conventional Commits 规范
  • 你不得推送到远程仓库
  • 如果 task_description 是 .code-task.md，则在提交前将 frontmatter 更新为 status: completed 和 completed: <date>
  • 在 progress.md 中记录提交哈希

💬 有关特定模式的交互指导，请参阅 Mode Behavior

预期成果

  • 满足所有要求的完整且经过充分测试的实现
  • 全面的测试套件，用于验证实现
  • 遵循现有模式的整洁代码，优先考虑可读性，避免过度设计
  • 实现产物位于 {documentation_dir}/implementation/{task_name}/（context.md、plan.md、progress.md、logs/）
  • 使用规范的提交消息正确提交更改

示例

功能实现

输入：

task_description: "Create a utility function that validates email addresses"
mode: "interactive"

预期流程：

  1. 检查是否存在 CODEASSIST.md，并查找指令文件
  2. 根据现有文件（pom.xml、package.json 等）判断项目类型
  3. 在 .sop/planning/implementation/email-validator/ 中设置目录结构
  4. 梳理需求并创建上下文文档
  5. 为有效/无效的电子邮件格式规划测试场景
  6. 先实现测试（TDD 方法）
  7. 实现验证函数
  8. 使用规范的提交消息提交更改

故障排除

目录/权限问题： 尽可能创建目录；如果遇到权限问题，告知用户并建议替代方案。

构建失败： 查看 CODEASSIST.md 中的指导，确认目录正确，尝试干净构建，并检查依赖项。

多包协调： 确认依赖顺序，按顺序构建，并为每个包分别创建提交。

任务文件 Frontmatter 问题： 如果 Frontmatter 缺失或格式错误，则跳过更新。不要因 Frontmatter 问题导致任务失败。

实现难题： 在 progress.md 中记录，并提出替代方案。在交互模式下请求指导；在自动模式下选择最有希望的方案并记录决策。

产物

• {documentation_dir}/implementation/{task_name}/context.md — 工作区结构、需求、模式、依赖项和实现路径 • {documentation_dir}/implementation/{task_name}/plan.md — 测试场景、实现策略 • {documentation_dir}/implementation/{task_name}/progress.md — 执行跟踪、TDD 周期、提交状态、难题 • {documentation_dir}/implementation/{task_name}/logs/ — 构建输出

评论

支持 Markdown