skill-writing-plans

宿主：Codex CLI — 此技能为 Claude Code 设计，并已适配 Codex。 交叉引用命令在 Codex 中使用已安装的技能名称，而不是 /octo:* 斜杠命令。 使用当前 Codex shell 和子 Agent 工具。在当前会话尚未提供相关能力之前，不要声称可用某个提供商、模型或宿主子 Agent。 有关宿主工具的对应项，请参阅 skills/blocks/codex-host-adapter.md。

编写计划

从已安装的插件中加载 skills/blocks/engineering-method-selection.md， 并仅应用与此任务相关的方法。保留此入口的执行约定 和输出格式。将引用的技能作为指令阅读； 不要递归调用当前命令，也不要从席位发起提供商调用。

必须遵守 — 不得跳过

调用此技能时，必须按照下方结构编写完整的实施计划。严禁：

• 跳过计划，直接开始实施
• 编写模糊的提纲，而非适用于零背景读者的计划
• 认为任务“足够简单”，因此不需要计划
• 省略文件路径、完整代码、测试说明或验证步骤

用户要求的是计划，而非实施。请先编写计划。

你的第一行输出必须是： 🐙 **CLAUDE OCTOPUS ACTIVATED** - Implementation Planning

概述

编写全面的实施计划，并假定工程师对代码库毫无背景，且品味不佳。

记录所有细节：要修改哪些文件、完整代码、如何测试以及如何验证。

原则： DRY。YAGNI。TDD。频繁提交。

任务前先处理决策

在编写实施任务之前，为尚未解决的决策构建依赖关系图。 决策记录应包含问题、所需证据、依赖项、负责人、解决方案和解除阻塞的实施工作。使用仓库配置的跟踪器。Beads 不是最终用户要求。

决策状态为 open、claimed、resolved、superseded 和 blocked，并映射到原生跟踪器状态或标签。只有基于证据或有记录的人类决策才能解决决策。如果新证据使某个决策失效，应重新打开其依赖工作并说明原因。循环意味着工作尚未准备就绪；应重新拆分决策，而不是将任务标记为就绪。

通过跟踪器的原子操作认领任务，并在写入前读取所有权信息。如果无法原子认领，则指定一名集成负责人。切勿覆盖他人的认领。如果跟踪器不可用，应将明确标注为未登记的提案保存到现有计划存储中，停止写入跟踪器，且不得伪造 ID 或迁移数据库。

计划文档结构

标题（必填）

# [Feature Name] Implementation Plan

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

**Estimated Time:** [X tasks × 5 min = Y minutes]


## Prerequisites

- [ ] [Any setup needed before starting]
- [ ] [Dependencies to install]
- [ ] [Files that must exist]

任务粒度

每个任务只能包含一个操作（2–5 分钟）：

好（单一操作）	不好（多个操作）
“编写失败的测试”	“编写测试并实施”
“运行测试以确认其失败”	“让它正常工作”
“编写通过测试所需的最少代码”	“添加此功能”
“提交并附上说明”	“完成此功能”

任务模板

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/new-file.ts`
- Modify: `exact/path/to/existing.ts` (lines 45-67)
- Test: `tests/exact/path/to/test.spec.ts`

**Step 1: Write failing test**

```typescript
// tests/exact/path/to/test.spec.ts
describe('ComponentName', () => {
  it('should do specific thing', () => {
    const result = functionName(input);
    expect(result).toBe(expected);
  });
});

步骤 2：运行测试以确认其失败

npm test tests/exact/path/to/test.spec.ts

预期输出：

FAIL: expected 'expected' but got undefined

步骤 3：编写最少的代码

// exact/path/to/new-file.ts
export function functionName(input: InputType): OutputType {
  // Minimal implementation
  return expected;
}

步骤 4：运行测试以确认其通过

npm test tests/exact/path/to/test.spec.ts

预期输出：

PASS: 1/1 tests passed

步骤 5：提交

git add tests/exact/path/to/test.spec.ts exact/path/to/new-file.ts
git commit -m "feat(component): add specific functionality"

## Example: Complete Task

```markdown
### Task 3: Add Email Validation

**Files:**
- Create: `src/validators/email.ts`
- Test: `tests/validators/email.spec.ts`

**Step 1: Write failing test**

```typescript
// tests/validators/email.spec.ts
import { validateEmail } from '../src/validators/email';

describe('validateEmail', () => {
  it('returns error for empty email', () => {
    const result = validateEmail('');
    expect(result).toEqual({ valid: false, error: 'Email required' });
  });

  it('returns error for invalid format', () => {
    const result = validateEmail('not-an-email');
    expect(result).toEqual({ valid: false, error: 'Invalid email format' });
  });

  it('returns valid for correct email', () => {
    const result = validateEmail('[email protected]');
    expect(result).toEqual({ valid: true });
  });
});

步骤 2：运行测试以确认其失败

npm test tests/validators/email.spec.ts

预期结果：Cannot find module '../src/validators/email'

步骤 3：编写最少的代码

// src/validators/email.ts
interface ValidationResult {
  valid: boolean;
  error?: string;
}

export function validateEmail(email: string): ValidationResult {
  if (!email || !email.trim()) {
    return { valid: false, error: 'Email required' };
  }

  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  if (!emailRegex.test(email)) {
    return { valid: false, error: 'Invalid email format' };
  }

  return { valid: true };
}

步骤 4：运行测试以确认其通过

npm test tests/validators/email.spec.ts

预期结果：PASS: 3/3 tests passed

步骤 5：提交

git add src/validators/email.ts tests/validators/email.spec.ts
git commit -m "feat(validators): add email validation with tests"

## Integration with Claude Octopus

### Using Octopus for Plan Execution

After creating a plan, offer execution options:

```markdown
## Execution Options

**1. Sequential (this session)**
Execute tasks one by one with verification between each.

**2. Parallel (octopus tangle)**
Use Claude Octopus to parallelize independent tasks:
```bash
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh tangle "Execute implementation plan for [feature]"

3. 完整工作流（章鱼拥抱） 调研 → 定义 → 实施 → 交付：

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh embrace "Implement [feature] per plan"

### Plan Storage (Claude Code v2.1.10)

Claude Octopus uses session-aware plan storage. Plans are automatically saved to:

~/.claude-octopus/plans/${CLAUDE_SESSION_ID}/YYYY-MM-DD-feature-name.md

This integrates with Claude Code's `plansDirectory` setting. To customize:

```json
// settings.json
{
  "plansDirectory": "~/.claude-octopus/plans"
}

对于项目本地计划，请保存到 docs/plans/：

mkdir -p docs/plans
# docs/plans/2026-01-17-user-authentication.md

优质计划检查清单

• 每项任务耗时 2-5 分钟（单个操作）
• 明确的文件路径（而不是“在 utils 文件夹中”）
• 完整代码（而不是“添加验证逻辑”）
• 明确的命令及预期输出
• TDD：先测试，再实现
• 每项任务完成后提交

常见错误

错误	修正方法
“添加验证”	展示确切代码
“更新测试”	展示确切的测试代码
“在配置文件中”	config/app.config.ts 第 23 行
“运行测试”	npm test path/to/specific.spec.ts
大型任务（30 分钟以上）	拆分为耗时 2-5 分钟的小步骤
没有验证	添加“运行 X，预期结果为 Y”

何时制定计划

场景	是否使用计划？
多步骤功能（3 项以上任务）	是
简单的 bug 修复（1 项任务）	否，直接处理
范围不确定	是（有助于理清思路）
委派给子 Agent	是（可在零上下文的情况下执行）
复杂重构	是
配置变更	否

相关技能

• test-driven-development - 每项任务都遵循 TDD 循环
• verification-before-completion - 验证每个步骤
• finishing-branch - 完成所有任务后执行

核心要点

Plan exists → Engineer with zero context can execute
Otherwise → Not a complete plan

明确路径。完整代码。验证步骤。不做假设。