code-assist

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Assist

代码辅助工具（Code Assist）

Overview

概述

Guides implementation of code tasks using test-driven development in an Explore, Plan, Code, Commit workflow. Balances automation with user collaboration while adhering to existing package patterns and prioritizing readability and extensibility.

采用探索、规划、编码、提交的工作流，通过测试驱动开发（TDD）指导代码任务的实现。在遵循现有包模式、优先保证可读性与可扩展性的前提下，平衡自动化与用户协作。

Parameters

参数

task_description (required): Task specification, rough idea, file path to
```
.code-task.md
```
, or URL
additional_context (optional): Supplementary information for implementation context
documentation_dir (optional, default: ".sop/planning"): Directory for planning documents
repo_root (optional, default: current working directory): Repository root for code implementation
task_name (optional): Short descriptive name (auto-generated if not provided)
mode (optional, default: "auto"): "interactive" (confirmation at each step) or "auto" (autonomous execution)

Constraints:

You MUST ask for all parameters upfront in a single prompt to avoid repeated interruptions
You MUST validate inputs: normalize mode to "interactive"/"auto", verify paths, generate task_name if needed

task_description（必填）：任务规格说明、初步想法、指向
```
.code-task.md
```
的文件路径或URL
additional_context（可选）：用于实现上下文的补充信息
documentation_dir（可选，默认值：
```
.sop/planning
```
）：规划文档的存储目录
repo_root（可选，默认值：当前工作目录）：代码实现的仓库根目录
task_name（可选）：简短描述性名称（未提供时自动生成）
mode（可选，默认值："auto"）："interactive"（每一步需确认）或"auto"（自主执行）

约束条件：

必须在单个提示中一次性索要所有参数，避免反复中断
必须验证输入：将mode标准化为"interactive"/"auto"，验证路径，必要时生成task_name

Mode Behavior

模式行为

Apply these patterns throughout all steps:

Interactive Mode: Present actions for confirmation. Explain pros/cons when multiple approaches exist. Ask clarifying questions. Pause at key decision points. Provide educational context.

Auto Mode: Execute autonomously. Document all decisions and reasoning in progress.md. Select the most appropriate approach and document why. Provide comprehensive summaries at completion.

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

交互式模式（Interactive Mode）： 展示待确认的操作。当存在多种实现方式时，说明各方式的优缺点。提出澄清问题。在关键决策节点暂停。提供教学性上下文信息。

自动模式（Auto Mode）： 自主执行所有操作。在progress.md中记录所有决策与推理过程。选择最合适的实现方式并记录原因。完成后提供全面的总结。

Important Notes

重要说明

Separation of Concerns: Documentation goes in

{documentation_dir}

. Code (tests and implementation) goes in

repo_root

. Never mix them. Documentation should guide implementation with high-level concepts — not provide it. When including code snippets in documentation, keep them brief and clearly label them as examples or references.

CODEASSIST.md Integration: If CODEASSIST.md exists in repo_root, read it and apply its constraints throughout.

关注点分离： 文档存储在

{documentation_dir}

中。代码（测试用例与实现代码）存储在repo_root中。绝对不能混合存放。文档应通过高层级概念指导实现——而非直接提供实现代码。在文档中包含代码片段时，需保持简洁，并明确标记为示例或参考。

CODEASSIST.md集成： 若repo_root中存在CODEASSIST.md文件，需读取该文件并在整个流程中遵循其约束条件。

Steps

步骤

1. Setup

1. 准备阶段（Setup）

Initialize the project environment and create necessary directory structures.

Constraints:

You MUST create
```
{documentation_dir}/implementation/{task_name}/
```
(with logs subdirectory) and verify it exists before proceeding
You MUST discover instruction files (CODEASSIST.md, README.md, CONTRIBUTING.md, ARCHITECTURE.md, etc.) and summarize relevant information in context.md
You MUST create context.md (project structure, requirements, patterns, dependencies) and progress.md (execution tracking with markdown checklists)
If task_description points to a
```
.code-task.md
```
with YAML frontmatter, update
```
status: in_progress
```
and
```
started: <date>
```
(if not already set)

💬 See Mode Behavior for mode-specific interaction guidance

初始化项目环境并创建必要的目录结构。

约束条件：

必须创建
```
{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. Explore Phase

2. 探索阶段（Explore Phase）

2.1 Analyze Requirements and Context

2.1 分析需求与上下文

Analyze the task description and existing documentation to identify core functionality, edge cases, and constraints.

Constraints:

You MUST produce a clear list of functional requirements and acceptance criteria, even from rough descriptions
You MUST determine appropriate file paths, language, and alignment with existing project structure
In interactive mode, discuss requirements with the user, clarify ambiguities, and validate your understanding

💬 See Mode Behavior for mode-specific interaction guidance

分析任务描述与现有文档，识别核心功能、边缘情况与约束条件。

约束条件：

必须生成清晰的功能需求与验收标准列表，即使输入是粗略的描述
必须确定合适的文件路径、开发语言，并与现有项目结构保持一致
在交互式模式下，与用户讨论需求，澄清模糊点，验证你的理解

💬 请参考模式行为获取模式相关的交互指导

2.2 Research Existing Patterns

2.2 研究现有模式

Search for similar implementations and identify interfaces, libraries, and components the implementation will interact with.

Constraints:

You MUST search the repository for relevant code, patterns, and conventions
You MUST create a dependency map and update context.md with implementation paths

💬 See Mode Behavior for mode-specific interaction guidance

搜索类似的实现案例，识别实现过程中需要交互的接口、库与组件。

约束条件：

必须在仓库中搜索相关代码、模式与约定
必须生成依赖关系图，并在context.md中更新实现路径

💬 请参考模式行为获取模式相关的交互指导

3. Plan Phase

3. 规划阶段（Plan Phase）

3.1 Design Test Strategy

3.1 设计测试策略

Create test scenarios covering normal operation, edge cases, and error conditions.

Constraints:

You MUST cover all acceptance criteria with at least one test scenario
You MUST define explicit input/output pairs and save scenarios to plan.md
You MUST design tests that will initially fail (no mock implementations during design)

💬 See Mode Behavior for mode-specific interaction guidance

创建覆盖正常操作、边缘情况与错误场景的测试用例。

约束条件：

必须为所有验收标准至少设计一个测试场景
必须定义明确的输入/输出对，并将场景保存到plan.md中
必须设计初始会失败的测试用例（设计阶段不使用模拟实现）

💬 请参考模式行为获取模式相关的交互指导

3.2 Implementation Planning & Tracking

3.2 实现规划与跟踪

Outline the high-level structure and create an implementation plan.

Constraints:

You MUST save the plan to plan.md with key implementation tasks
You MUST maintain an implementation checklist in progress.md using markdown checkbox format
In interactive mode, present multiple approaches with pros/cons and discuss trade-offs

💬 See Mode Behavior for mode-specific interaction guidance

概述高层级结构并创建实现计划。

约束条件：

必须将计划保存到plan.md中，包含关键实现任务
必须在progress.md中使用Markdown复选框格式维护实现进度清单
在交互式模式下，展示多种实现方式及其优缺点，并讨论权衡方案

💬 请参考模式行为获取模式相关的交互指导

4. Code Phase

4. 编码阶段（Code Phase）

Phase-wide constraints:

You MUST place all code (tests and implementation) in repo_root, never in documentation_dir
You MUST verify tests/builds pass before advancing to the next sub-step
You MUST follow the existing codebase's conventions (naming, patterns, error handling, testing style)
Pipe build output to
```
{documentation_dir}/implementation/{task_name}/logs/
```
and search for success/failure indicators

全阶段约束：

必须将所有代码（测试用例与实现代码）存放在repo_root中，绝对不能存放在documentation_dir中
必须在进入下一个子步骤前验证测试/构建是否通过
必须遵循现有代码库的约定（命名、模式、错误处理、测试风格）
将构建输出导入
```
{documentation_dir}/implementation/{task_name}/logs/
```
目录，并搜索成功/失败标识

4.1 Implement Test Cases

4.1 实现测试用例

Write test cases following strict TDD principles.

Constraints:

You MUST implement tests for ALL requirements before writing ANY implementation code
You MUST execute tests to verify they fail as expected, documenting failure reasons
You MUST follow the testing framework conventions used in the existing codebase

💬 See Mode Behavior for mode-specific interaction guidance

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

约束条件：

必须在编写任何实现代码前，为所有需求实现测试用例
必须执行测试用例以验证其是否如预期失败，并记录失败原因
必须遵循现有代码库所使用的测试框架约定

💬 请参考模式行为获取模式相关的交互指导

4.2 Develop Implementation Code

4.2 开发实现代码

Write implementation code to pass the tests, focusing on simplicity and correctness first.

Constraints:

You MUST follow the TDD cycle: RED → GREEN → REFACTOR
You MUST implement only what is needed to make current tests pass (YAGNI, KISS, SOLID)
You MUST execute tests after each implementation step to verify they pass

💬 See Mode Behavior for mode-specific interaction guidance

编写实现代码以通过测试用例，优先关注简洁性与正确性。

约束条件：

必须遵循TDD循环：红（RED）→ 绿（GREEN）→ 重构（REFACTOR）
必须仅实现当前测试用例通过所需的功能（遵循YAGNI、KISS、SOLID原则）
必须在每一步实现后执行测试用例以验证是否通过

💬 请参考模式行为获取模式相关的交互指导

4.3 Refactor and Optimize

4.3 重构与优化

Review the implementation for simplification, improvement, and convention alignment.

Constraints:

You MUST verify all tests and builds pass before starting — fix any failures first
You MUST align implementation with surrounding codebase conventions (naming, structure, error handling, imports, logging)
You MUST maintain test-passing status throughout refactoring

💬 See Mode Behavior for mode-specific interaction guidance

审查实现代码，进行简化、改进与约定对齐。

约束条件：

必须在开始重构前验证所有测试与构建均通过——先修复所有失败项
必须使实现代码与周边代码库的约定保持一致（命名、结构、错误处理、导入、日志）
必须在重构过程中始终保持测试用例通过的状态

💬 请参考模式行为获取模式相关的交互指导

4.4 Validate Implementation

4.4 验证实现

Verify the implementation is complete and correct.

Constraints:

You MUST run the full test suite and build, verifying all pass
You MUST verify all implementation plan items are completed
You MUST NOT claim completion while any tests are failing

💬 See Mode Behavior for mode-specific interaction guidance

验证实现是否完整且正确。

约束条件：

必须运行完整的测试套件与构建流程，验证所有项均通过
必须验证所有实现计划项均已完成
任何测试用例失败时，均不得声称实现已完成

💬 请参考模式行为获取模式相关的交互指导

5. Commit Phase

5. 提交阶段（Commit Phase）

Draft a conventional commit message and perform the git commit.

Constraints:

You MUST NOT commit until builds AND tests are verified passing
You MUST follow the Conventional Commits specification
You MUST NOT push to remote repositories
If task_description was a
```
.code-task.md
```
, update frontmatter to
```
status: completed
```
and
```
completed: <date>
```
before committing
Document the commit hash in progress.md

💬 See Mode Behavior for mode-specific interaction guidance

编写符合规范的提交信息并执行git commit操作。

约束条件：

必须在确认构建与测试均通过后再执行提交
必须遵循Conventional Commits（规范化提交）规范
不得推送到远程仓库
若task_description指向
```
.code-task.md
```
文件，需在提交前更新前置元数据为
```
status: completed
```
与
```
completed: <date>
```
在progress.md中记录提交哈希值

💬 请参考模式行为获取模式相关的交互指导

Desired Outcome

预期成果

Complete, well-tested implementation meeting all requirements
Comprehensive test suite validating the implementation
Clean code following existing patterns, prioritizing readability, avoiding over-engineering
Implementation artifacts in
```
{documentation_dir}/implementation/{task_name}/
```
(context.md, plan.md, progress.md, logs/)
Properly committed changes with conventional commit messages

符合所有需求的完整、测试充分的实现
验证实现的全面测试套件
遵循现有模式的简洁代码，优先保证可读性，避免过度设计
存储在
```
{documentation_dir}/implementation/{task_name}/
```
中的实现工件（context.md、plan.md、progress.md、logs/）
带有规范化提交信息的正确提交变更

Examples

示例

Feature Implementation

功能实现

Input:

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

Expected Process:

Check for CODEASSIST.md and discover instruction files
Detect project type from existing files (pom.xml, package.json, etc.)
Set up directory structure in .sop/planning/implementation/email-validator/
Explore requirements and create context documentation
Plan test scenarios for valid/invalid email formats
Implement tests first (TDD approach)
Implement the validation function
Commit with conventional commit message

输入：

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

预期流程：

检查是否存在CODEASSIST.md并查找指令文件
从现有文件（pom.xml、package.json等）检测项目类型
在.sop/planning/implementation/email-validator/中创建目录结构
探索需求并创建上下文文档
规划有效/无效邮箱格式的测试场景
先实现测试用例（TDD方式）
实现邮箱验证函数
使用规范化提交信息执行提交

Troubleshooting

故障排除

Directory/Permission Issues: Create directories if possible, inform user of permission issues, suggest alternatives.

Build Failures: Check CODEASSIST.md for guidance, verify correct directory, try clean builds, check dependencies.

Multi-Package Coordination: Verify dependency order, build in order, create separate commits per package.

Task File Frontmatter Issues: Skip frontmatter updates if missing/malformed. Don't fail the task due to frontmatter issues.

Implementation Challenges: Document in progress.md, propose alternatives. In interactive mode ask for guidance; in auto mode select the most promising approach and document the decision.

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

构建失败： 查看CODEASSIST.md获取指导，验证目录是否正确，尝试清理构建，检查依赖。

多包协调： 验证依赖顺序，按顺序构建，为每个包创建单独的提交。

任务文件前置元数据问题： 若前置元数据缺失或格式错误，跳过更新操作。不得因前置元数据问题导致任务失败。

实现挑战： 在progress.md中记录问题，提出替代方案。在交互式模式下向用户寻求指导；在自动模式下选择最有前景的方案并记录决策过程。

Artifacts

工件

•

{documentation_dir}/implementation/{task_name}/context.md

— Workspace structure, requirements, patterns, dependencies, implementation paths •

{documentation_dir}/implementation/{task_name}/plan.md

— Test scenarios, implementation strategy •

{documentation_dir}/implementation/{task_name}/progress.md

— Execution tracking, TDD cycles, commit status, challenges •

{documentation_dir}/implementation/{task_name}/logs/

— Build outputs

•

{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/

— 构建输出