
idd
Intent Driven Development - Complete toolkit for Intent-driven development
- version
- 1.4.1
- GitHub stars
- 17
Install
/plugin install idd@iddRun it inside Claude Code after adding the marketplace with /plugin marketplace add ArcBlock/idd.
Contents
Discovered from sourceSkills 13
Intent Assess
评估项目是否适合 IDD,并教育 IDD 方法论。
两个模式
1. 评估模式 (Assessment)
/intent-assess
分析当前项目,评估是否适合采用 IDD。
2. 学习模式 (Learning)
/intent-assess --learn
教育 IDD 方法论,解释核心概念。
评估模式
工作流程
/intent-assess
↓
┌───────────────────────────────────┐
│ Phase 1: 项目分析 │
│ - 项目类型识别 │
│ - 代码库规模 │
│ - 现有文档情况 │
│ - 团队协作模式 │
└─────────────┬─────────────────────┘
↓
┌───────────────────────────────────┐
│ Phase 2: 适配度评估 │
│ - 计算匹配分数 │
│ - 识别优势和挑战 │
└─────────────┬─────────────────────┘
↓
┌───────────────────────────────────┐
│ Phase 3: 建议 │
│ - 是否推荐 IDD │
│ - 如何开始 │
│ - 替代方案(如不适合) │
└───────────────────────────────────┘
评估维度
| 维度 | 有利于 IDD | 不利于 IDD |
|---|---|---|
| 项目类型 | 系统软件、框架、库 | 简单脚本、一次性项目 |
| 代码规模 | 中大型 (>5k LOC) | 小型 (<1k LOC) |
| 团队协作 | 多人协作、AI 辅助 | 单人独立开发 |
| 架构复杂度 | 多模块、需要边界 | 单模块、简单结构 |
| 迭代方式 | 持续迭代、长期维护 | 一次性交付 |
| AI 工具使用 | 使用 Claude/Copilot | 纯人工开发 |
评估报告示例
# IDD Assessment Report
> Project: ainecore
> Date: 2026-01-19
## 适配度评分: 85/100 ⭐⭐⭐⭐
## 项目特征
| 特征 | 当前状态 | IDD 契合度 |
|------|---------|-----------|
| 项目类型 | 框架/平台 | ✅ 高 |
| 代码规模 | ~15k LOC | ✅ 高 |
| 模块数量 | 12 个 | ✅ 高 |
| 团队规模 | 3 人 + AI | ✅ 高 |
| 现有文档 | 部分 | 🟡 中 |
## 优势
- ✅ 多模块架构,需要清晰边界定义
- ✅ 使用 AI 辅助开发,Intent 可指导 AI
- ✅ 长期维护项目,文档价值高
- ✅ 已有部分设计文档,可迁移
## 挑战
- ⚠️ 需要建立 Intent 编写习惯
- ⚠️ 现有代码需要补充 Intent
- ⚠️ 团队需要学习 IDD 方法
## 建议
### 推荐: 采用 IDD ✅
该项目非常适合 IDD:
1. 多模块架构需要清晰的边界和契约
2. AI 辅助开发可以直接使用 Intent 作为上下文
3. 长期维护价值高
### 启动建议
1. **从核心模块开始**
- 先为 `src/core/` 编写 Intent
- 建立 Intent 模板和规范
2. **渐进式推广**
- 新功能必须先写 Intent
- 老代码逐步补充
3. **工具配套**
- 安装 IDD plugin
- 配置 CI/CD 集成
### 预期收益
- 🎯 AI 编码效率提升 ~30%
- 🎯 架构边界更清晰
- 🎯 新成员 onboard 更快
- 🎯 减少 "文档过时" 问题
学习模式
交互式教学
/intent-assess --learn
通过问答方式教授 IDD:
┌───────────────────────────────────┐
│ 欢迎学习 IDD! │
│ │
│ 我将介绍: │
│ 1. 什么是 IDD │
│ 2. IDD vs TDD vs SDD │
│ 3. Intent 文件结构 │
│ 4. 实际案例 │
│ │
│ 你想从哪个话题开始? │
└───────────────────────────────────┘
核心概念讲解
1. 什么是 IDD
开发方法论演进:
Traditional: Code → Test → Docs
(文档经常过时)
SDD: Spec → Code → Test
(Spec 分散,难以维护)
TDD: Test → Code → Docs
(测试不能捕捉设计理由)
IDD: Intent → Test → Code → Sync
(Intent 作为唯一真相来源)
2. Intent 三层结构
┌─────────────────────────────────────┐
│ Layer 1: 结构图 (Structure) │
│ - 目录结构、数据结构、模块关系 │
│ - ASCII 图优先 │
├─────────────────────────────────────┤
│ Layer 2: 约束规则 (Constraints) │
│ - 依赖方向、边界规则、不变式 │
│ - 可转化为测试断言 │
├─────────────────────────────────────┤
│ Layer 3: 行为示例 (Examples) │
│ - 输入 → 输出 示例 │
│ - 边界情况 │
└─────────────────────────────────────┘
3. IDD vs SDD 对比
| 维度 | SDD | IDD |
|------|-----|-----|
| 组织方式 | 按类型 (功能/UX/技术) | 按模块 |
| 核心载体 | 文字描述 | 结构图 |
| 粒度 | 细分 User Story | 完整 Pattern |
| Task 管理 | 独立 Task 文件 | AI 自主分解 |
| LLM 友好度 | 需要拼装上下文 | 一次理解完整 |
4. 实际案例
展示一个真实的 Intent 文件,解释各部分作用。
快速参考
/intent-assess --learn --topic <topic>
可选 topic:
what- 什么是 IDDvs-sdd- IDD vs SDD 对比vs-tdd- IDD vs TDD 对比structure- Intent 文件结构workflow- IDD 工作流程approval- Section 审批机制best-practices- 最佳实践
与其他命令配合
/intent-assess # 评估项目
↓ (如果适合)
/intent-assess --learn # 学习 IDD
↓
/intent-init # 初始化 IDD
↓
/intent-interview # 创建 Intent
Intent Build Now
Start building from Intent. Validates completeness, then chooses execution path.
Workflow
/intent-build-now [path]
↓
Locate Intent + plan.md
↓
Validate completeness ──→ Incomplete? ──→ Show gaps, suggest /intent-plan
↓
Check for TaskSwarm
│
├── Has TaskSwarm + TASK.yaml ──→ Delegate to /swarm run
│
└── No TaskSwarm ──→ Execute TDD phases directly
Step 1: Locate Files
Search for Intent files in order:
- User-specified path
intent/{name}/directories- Current directory
Required files:
INTENT.md- The intent documentplan.md- Execution plan with test matrix
Optional:
TASK.yaml- TaskSwarm status file
If plan.md missing:
plan.md not found.
Run /intent-plan first to generate the execution plan.
Step 2: Validate Intent Completeness
Required Sections in INTENT.md
| Section | Purpose | How to Fix |
|---|---|---|
| Responsibilities | What it does / doesn't do | Use /intent-interview to clarify scope |
| Structure | ASCII diagram of components | Add ## Structure with ASCII diagram |
| API | Function signatures | Define key interfaces in ## API |
Required in plan.md
| Check | Criteria |
|---|---|
| Phases | Has ## Phase 0: or more phases |
| Tests | Each phase has 6 test categories |
| E2E Gate | Each phase has ### E2E Gate |
| Checkboxes | Uses - [ ] format |
If Not Ready
## Intent Validation: NEEDS WORK
Missing elements:
1. **plan.md missing E2E Gate for Phase 1**
- Add `### E2E Gate` with verification script
2. **plan.md Phase 0 missing Data Leak tests**
- Add `#### Data Leak` section with test cases
Run /intent-plan to regenerate, or fix manually.
Step 3: Choose Execution Path
Path A: TaskSwarm Available
Detect TaskSwarm by checking:
TASK.yamlexists in intent directory- TaskSwarm plugin is installed (check for
/swarmskill)
If both conditions met:
## Intent Validation: PASSED ✓
TaskSwarm detected. Delegating execution...
Your Intent is ready. Run:
/swarm run {task_name}
Or for continuous execution:
/swarm run-all
TaskSwarm will:
- Claim the task atomically
- Execute phases with TDD discipline
- Update checkboxes in plan.md
- Commit after each phase
- Push to remote
Do NOT execute phases yourself when TaskSwarm is available.
Path B: No TaskSwarm (Direct Execution)
If TaskSwarm not available:
## Intent Validation: PASSED ✓
No TaskSwarm detected. Executing directly...
Starting Phase 0: {phase_name}
Then execute TDD loop for each phase:
For each Phase:
1. Read ### Tests section
2. For each unchecked test `- [ ]`:
a. Write test code (if not exists)
b. Run test → expect failure (red)
c. Write implementation
d. Run test → expect pass (green)
e. Update plan.md: `- [ ]` → `- [x]`
3. Run E2E Gate script
4. Git commit: "feat({scope}): Phase {n} - {phase_name}"
5. Continue to next Phase
Step 4: Completion
After all phases complete:
## Build Complete ✓
All phases executed:
- Phase 0: {name} ✓
- Phase 1: {name} ✓
Next steps:
- Run /intent-sync to update Intent with confirmed details
- Run /intent-check to verify consistency
Integration
/intent-interview # Create Intent from scratch
↓
/intent-review # Section-by-section approval
↓
/intent-plan # Generate plan.md + TASK.yaml
↓
/intent-build-now # THIS SKILL
↓
┌───────────────────────────────────────┐
│ Has TaskSwarm? │
│ Yes → /swarm run (delegate) │
│ No → Execute TDD directly │
└───────────────────────────────────────┘
↓
/intent-sync # Sync confirmed details back
TDD Execution Standards (Direct Mode)
When executing without TaskSwarm, follow strict TDD:
Test Categories (All 6 Required)
- Happy Path - Normal expected usage
- Bad Path - Invalid inputs, error conditions
- Edge Cases - Boundary conditions
- Security - Vulnerability prevention
- Data Leak - Information exposure prevention
- Data Damage - Data integrity protection
TDD Discipline
- Tests First: Write ALL tests before implementation
- Red-Green-Refactor: Verify test fails, implement, verify pass
- No Skip: Every checkbox must be completed
- Commit Per Phase: One commit after each phase passes
E2E Gate Enforcement
Each phase's E2E Gate script MUST pass before proceeding:
# Run the E2E Gate script from plan.md
# Example: pnpm test -- --grep "Phase 0"
# If fails: Stop and fix
# If passes: Continue to next phase
Tips
- Prefer TaskSwarm - It handles concurrency, heartbeat, and recovery
- Don't force incomplete Intents - Missing plan.md means not ready
- Respect checkboxes - They're the source of truth for progress
- Commit frequently - One commit per phase, not one mega-commit
Intent Changes
设计文档的结构化变更提案与协作 Review 工具。
核心概念
Change Proposal
每个变更是一个独立提案:
| 字段 | 说明 |
|---|---|
| ID | 唯一标识 (C001, C002...) |
| Type | ADD / MODIFY / REPLACE / DELETE |
| Status | PENDING / ACCEPTED / REJECTED |
| Target | 变更位置 |
| Before/After | 变更内容 |
| Decision | 决策记录 (reviewer, timestamp, comment) |
状态流
PENDING ──accept──> ACCEPTED ──finalize──> Applied
│
└──reject──> REJECTED
命令
| 命令 | 说明 |
|---|---|
/intent-changes start <file> | 启动或恢复 review |
/intent-changes propose | 提出变更建议 |
/intent-changes accept <id> | 接受变更 |
/intent-changes reject <id> | 拒绝变更 |
/intent-changes status | 查看当前状态 |
/intent-changes finalize | 交互式 apply |
工作流程
/intent-changes start <file>
↓
┌───────────────────┐
│ 检查 .reviews/ │
│ 有则恢复 │
│ 无则创建 │
└─────────┬─────────┘
↓
/intent-changes propose
↓
┌───────────────────────────────────────┐
│ 读取源文档 │
│ 与用户讨论变更内容 │
│ 生成 Change Proposal (C001, C002...) │
│ 写入 .reviews/{name}.review.md │
└─────────┬─────────────────────────────┘
↓
/intent-changes accept/reject
↓
┌───────────────────┐
│ 更新 status │
│ 记录 reviewer │
│ 记录 timestamp │
└─────────┬─────────┘
↓
/intent-changes finalize
↓
┌───────────────────────────────────────┐
│ 逐个显示 ACCEPTED 变更 │
│ 交互确认: Apply? [Y/n/view] │
│ Apply 到源文档 │
│ 生成变更摘要 │
└───────────────────────────────────────┘
执行步骤
命令: start
输入: 文件路径
步骤:
- 验证源文件存在
- 确定 review 文件路径:
.reviews/{basename}.review.md - 如果 review 文件存在:
- 读取并解析
- 显示当前状态概览
- 如果不存在:
- 创建
.reviews/目录(如不存在) - 创建 review 文件,写入 frontmatter
- 创建
- 设置当前 session 的 source 和 review 路径
输出:
Review session started.
Source: intent/specs/kind-system-spec.md
Review: .reviews/kind-system-spec.review.md
Status: 3 PENDING, 2 ACCEPTED, 1 REJECTED
Commands:
/intent-changes propose - 提出新变更
/intent-changes status - 查看详情
/intent-changes finalize - 应用变更
命令: propose
前置条件: 已执行 start
步骤:
- 读取源文档内容
- 读取当前 review 文件,获取已有提案
- 计算下一个 ID (如已有 C001-C005,下一个是 C006)
- 与用户讨论:
- 展示源文档结构
- 使用 AskUserQuestion 询问变更类型和位置
- 收集变更内容
- 生成 Change Proposal 块
- 追加到 review 文件
交互流程:
使用 AskUserQuestion:
- question: "你想对哪个部分提出变更?"
- header: "变更位置"
- options:
- "## Kind 定义" - 第一个 section
- "## Actions" - 第二个 section
- "## 示例" - 第三个 section
- "其他位置" - 手动指定
使用 AskUserQuestion:
- question: "变更类型是什么?"
- header: "变更类型"
- options:
- "ADD" - 新增内容
- "MODIFY" - 修改现有内容
- "REPLACE" - 替换整个 section
- "DELETE" - 删除内容
然后收集具体内容,生成提案。
命令: accept / reject
输入: 提案 ID,可选 comment/reason
语法:
/intent-changes accept C001
/intent-changes accept C001 --comment "LGTM"
/intent-changes reject C002 --reason "不同意这个改法"
步骤:
- 读取 review 文件
- 找到对应 ID 的提案
- 验证当前状态是 PENDING
- 更新状态为 ACCEPTED 或 REJECTED
- 添加 Decision 记录:
- reviewer: 从 git config user.name 或 $USER 获取
- timestamp: 当前日期
- comment: 用户提供的评论
- 写回 review 文件
Decision 格式:
**Decision:**
- ✓ @robmao (2026-01-21): "LGTM"
或拒绝时:
**Decision:**
- ✗ @robmao (2026-01-21): "不同意这个改法"
命令: status
输出详情:
Review: kind-system-spec.md
Source: intent/specs/kind-system-spec.md
Reviewers: @robmao, @claude
─────────────────────────────────
PENDING (2):
C002 [MODIFY] 修改 Kind 定义的措辞
C004 [ADD] 新增性能章节
ACCEPTED (3):
C001 [ADD] 新增 Action 分类说明
✓ @robmao (2026-01-21)
C003 [MODIFY] 调整示例代码
✓ @claude (2026-01-21)
C005 [DELETE] 删除过时章节
✓ @robmao (2026-01-21)
REJECTED (1):
C006 [REPLACE] 重写整个文档
✗ @robmao (2026-01-21): "改动太大"
─────────────────────────────────
Next: /intent-changes finalize (3 changes ready)
命令: finalize
前置条件: 至少有一个 ACCEPTED 的提案
步骤:
- 读取 review 文件,筛选 ACCEPTED 提案
- 按 Target 位置排序(从文档末尾往前,避免位置偏移)
- 对每个提案交互确认:
[1/3] C001 [ADD]: 新增 Action 分类说明
Target: After "## Actions"
Content to add:
┌────────────────────────────────────────┐
│ Actions 分为三类: │
│ - Inline: 同步执行,决定 commit 成功与否 │
│ - Deferred: 异步执行,失败不影响 commit │
│ - Observational: 只读,可以慢 │
└────────────────────────────────────────┘
Apply this change? [Y/n/view/quit]
用户选项:
Y(默认): Apply 并继续n: Skip 此变更(保持 ACCEPTED 状态但不 apply)view: 显示完整的 before/after diffquit: 中止 finalize
- Apply 变更到源文档
- 更新 review 文件:
- 已 apply 的标记为
[APPLIED] - 更新 frontmatter status 为
finalized(如果全部处理完)
- 已 apply 的标记为
- 输出摘要
Apply 摘要:
Finalize complete.
Applied: 2
C001 - 新增 Action 分类说明
C003 - 调整示例代码
Skipped: 1
C005 - 删除过时章节 (user chose to skip)
Source updated: intent/specs/kind-system-spec.md
Review archived: .reviews/kind-system-spec.review.md
Review 文件格式
Frontmatter
---
source: intent/specs/kind-system-spec.md
created: 2026-01-21
reviewers:
- robmao
- claude
status: active
---
status 值:
active: 进行中finalized: 已完成 applyabandoned: 已放弃
Change Proposal 块
---
## C001 [ADD] [PENDING]
> 简短描述
**Target:** After "## Actions"
**After:**
```markdown
新增的内容...
C002 [MODIFY] [ACCEPTED]
简短描述
Target: Section "## Kind 定义"
Before:
原内容...
After:
新内容...
Reason: 变更理由
Decision:
- ✓ @robmao (2026-01-21): "LGTM"
## 获取 Reviewer 名称
按优先级:
1. 命令参数 `--reviewer`
2. `git config user.name`
3. 环境变量 `$USER`
```bash
# 获取方式
git config user.name || echo $USER
边界
做什么
- ✓ 结构化管理变更提案
- ✓ 追踪决策过程
- ✓ 支持多 reviewer 署名
- ✓ 交互式 apply
不做什么
- ✗ 格式校验 → intent-validate
- ✗ Section 审批 → intent-review
- ✗ 设计质量判断 → intent-critique
- ✗ 实现一致性 → intent-sync
与其他工具配合
intent-interview → 创建 Intent
↓
intent-critique → 质疑设计
↓
/intent-changes → 管理变更提案 ← 本 Skill
↓
intent-review → 锁定 sections
↓
intent-plan → 开始实现
示例
独立 Review
# 开始
/intent-changes start intent/specs/tools-spec.md
# 提出建议
/intent-changes propose
# 决策
/intent-changes accept C001
/intent-changes reject C002 --reason "不需要"
# 应用
/intent-changes finalize
协作 Review
# A 启动并提建议
/intent-changes start spec.md
/intent-changes propose # C001-C003
# B 来 review
/intent-changes accept C001 --comment "Good"
/intent-changes reject C002 --reason "换个方式"
# A 提新方案
/intent-changes propose # C004 替代 C002
# B 接受
/intent-changes accept C004
# 最终 apply
/intent-changes finalize
Intent Check
触发 Intent 检查流程,是 intent-validate 和 intent-sync agents 的用户友好入口。
功能
- 格式验证 (intent-validate) - 检查 Intent 文件是否符合 IDD 规范
- 代码同步 (intent-sync) - 检查代码实现与 Intent 的一致性
- 综合报告 - 汇总两项检查结果
工作流程
/intent-check [options]
↓
┌───────────────────────────────────┐
│ 确定检查范围 │
│ - 指定路径 or 当前目录 │
│ - 单模块 or 全项目 │
└─────────────┬─────────────────────┘
↓
┌───────────────────────────────────┐
│ 调用 intent-validate agent │
│ → 格式合规报告 │
└─────────────┬─────────────────────┘
↓
┌───────────────────────────────────┐
│ 调用 intent-sync agent │
│ → 代码一致性报告 │
└─────────────┬─────────────────────┘
↓
┌───────────────────────────────────┐
│ 汇总报告 │
│ - 问题列表 │
│ - 修复建议 │
│ - 行动项 │
└───────────────────────────────────┘
使用方法
完整检查
/intent-check
检查当前目录的 Intent,包括格式验证和代码同步。
指定路径
/intent-check src/core/
检查指定模块。
仅格式验证
/intent-check --validate
只运行 intent-validate,检查 Intent 文件格式。
仅代码同步
/intent-check --sync
只运行 intent-sync,检查代码与 Intent 一致性。
全项目检查
/intent-check --all
扫描并检查项目中所有 Intent 文件。
Git 差异检查
/intent-check --git-diff origin/main
只检查相对于基准分支有变更的模块。
输出示例
# Intent Check Report
> 检查时间: 2026-01-19 14:30
> 检查范围: src/core/
## 概览
| 检查项 | 状态 | 问题数 |
|--------|------|--------|
| 格式验证 | ⚠️ | 3 |
| 代码同步 | ❌ | 5 |
## 格式问题 (intent-validate)
### ⚠️ 警告
1. `src/core/intent/INTENT.md:45`
- 缺少 ASCII 结构图
2. `src/core/intent/INTENT.md:78`
- API 定义缺少返回值说明
### ❌ 错误
1. `src/core/intent/INTENT.md:12`
- Section 标记语法错误: `::: lock` → `::: locked`
## 同步问题 (intent-sync)
### 新增未记录
| API | 文件 | 建议 |
|-----|------|------|
| `getChamberStats()` | chamber.js:89 | 添加到 Intent |
### 签名不一致
```diff
# deleteChamber
- Intent: deleteChamber(app, name)
+ Code: deleteChamber(app, name, options)
边界违规
| 规则 | 位置 | 说明 |
|---|---|---|
| 禁止直接拼接路径 | routes/apps.js:45 | 应使用 chamber.getPath() |
行动建议
立即修复 (P0)
- 修复 Section 标记语法错误
- 修复边界违规
建议修复 (P1)
- 更新 Intent: 添加
getChamberStats()API - 更新 Intent:
deleteChamber添加 options 参数
可选改进 (P2)
- 添加 ASCII 结构图
- 补充 API 返回值说明
## 退出码
| 码 | 含义 |
|----|------|
| 0 | 全部通过 |
| 1 | 有警告 |
| 2 | 有错误 |
可用于 CI/CD 集成:
```bash
/intent-check || exit 1
与其他命令配合
/intent-init # 初始化
↓
/intent-interview # 创建 Intent
↓
/intent-review # 审批
↓
[开发实现]
↓
/intent-check # ← 检查(本命令)
↓
修复问题 or 更新 Intent
↓
/intent-check # 再次检查直到通过
Intent Critique
设计质量的批判性审查。不检查格式,只检查"是否该这么设计"。
核心问题
每次 critique 回答一个问题:这个设计能更简单吗?
Anti-Accretion Rule: 净减
Critique 后总行数必须 ≤ 之前。 这是硬约束,不是建议。
Critique 只允许 4 种操作:
| 操作 | 说明 | 示例 |
|---|---|---|
| 删除 | 移除 section 或内容 | 删除未使用的插件系统设计 |
| 合并 | 多个 section 合为一个 | 将 Error Handling 合入 API Constraints |
| 拆分 | 移到独立 intent | §13-§18 从 ash 拆为 ash/agentic-patterns |
| 简化 | 用更少的行表达相同约束 | 5 行描述压缩为 2 行 |
禁止:
- ❌ 引入新概念或新 section
- ❌ 添加新分析框架
- ❌ 扩展现有 section 的范围
如果发现缺了什么,输出 gap flag,不直接填充:
Gap: intent 没有说明 failure handling。建议在下一轮 interview 中讨论。
如果确实需要加新内容,必须:
- 先删等量或更多旧内容
- 用户明确同意
- 最终行数仍然 ≤ 初始行数
检查维度
| 维度 | 信号 | 问题 |
|---|---|---|
| Over-engineering | 复杂的配置系统、插件架构、多层抽象 | "这个复杂度是当前需求驱动的吗?" |
| YAGNI | "未来可能需要"、"预留扩展点"、"支持多种..." | "删掉这个,MVP 还能工作吗?" |
| 过早抽象 | 只有一个实现的接口、只用一次的工具函数 | "现在真的需要这层抽象吗?" |
| 边界问题 | 模块间大量数据传递、循环依赖、职责模糊 | "这个边界切在这里自然吗?" |
| 隐藏复杂度 | 看似简单但实现困难的描述 | "这句话背后的实现复杂度是什么?" |
工作流程
/intent-critique [path]
↓
┌───────────────────┐
│ 读取 Intent 文件 │
│ 理解设计意图 │
└─────────┬─────────┘
↓
┌───────────────────┐
│ 逐维度分析 │
│ 识别可疑设计 │
└─────────┬─────────┘
↓
┌───────────────────────────────────────┐
│ 对每个发现,与用户讨论: │
│ │
│ 展示问题 + 简化建议 │
│ AskUserQuestion: │
│ - 接受简化 │
│ - 保留原设计(说明理由) │
│ - 跳过此项 │
└─────────┬─────────────────────────────┘
↓
┌───────────────────┐
│ 汇总 critique │
│ 可选更新 Intent │
└───────────────────┘
使用方法
# 审查指定 Intent
/intent-critique src/core/intent/INTENT.md
# 审查当前目录
/intent-critique
# 只分析不修改
/intent-critique --dry-run
执行步骤
0. 记录初始行数
第一步必须是计数。 在任何分析之前:
wc -l INTENT.md
# 记录为 before_lines
将 before_lines 记录下来,critique 结束时用于验证净减。
0.5 Convergence Check(修改 ≥ 3 次时自动触发)
检查 git log 中 INTENT.md 的提交次数。如果 ≥ 3 次,在正常 critique 之前先跑 convergence:
4 步 convergence 检查:
-
Anchor trace — 对每个 section 问:能追溯到 anchor 吗?
- 不能 → 标记为候选删除
-
Implementation match — 对每个 section 问:有对应的实现吗?
- 有实现 → 保留
- 没实现且不在 plan 里 → 标记为候选删除
-
Constraint vs Analysis — 对每个 section 问:这是约束还是分析?
- "Three Dimensions of Chat Experience" = 分析 → 精简或移到 appendix
- "INV-1: LLM is a Pure Function" = 约束 → 保留
-
Dedup with sub-intents — 有 section 跟子 intent 重复吗?
- 有 → 删掉,留一个链接
Convergence 输出格式:
## Convergence Check (triggered: 5 commits since last convergence)
### Anchor trace failures
- § Agentic Pattern Zones — cannot trace to "ASH 是 shell 语言"
- § Echo Deprecation — migration plan, not core spec
### Unimplemented sections
- § Template Registry — no code, not in plan
### Analysis (not constraint)
- § AI Agent 适配性分析 — 40 lines of analysis, 0 constraints
### Duplicated in sub-intents
- § Boot Sequence — duplicates kernel/bootloader INTENT.md §2
→ Candidates for removal: 4 sections, ~280 lines
跑完 convergence 后,进入正常 critique 流程。
0.7 读取 Records 索引
如果 records/INDEX.md 存在,先读取索引了解完整决策上下文:
- 哪些 interview 做过哪些决策
- 其他 AI(ChatGPT、Gemini 等)给过什么 review 意见
- 之前的 critique 记录
按需深入读取相关 record 文件。这解决了 context asymmetry —— 即使原始讨论发生在其他 AI 上,这里也有完整记录。
0.8 Devil's Advocate(独立评估)
起一个不带当前讨论 context 的 subagent,只给它:
- INTENT.md 全文
- Anchor 声明
让它独立回答 3 个问题:
- 这个 intent 最大的设计风险是什么?
- 哪些 section 看起来像分析而非约束?
- 如果只能保留 3 个 section,你保留哪些?
将 devil's advocate 的输出作为 critique 的额外输入,不直接采纳但用于交叉验证自己的判断。
1. 读取并理解 Intent
先完整阅读 Intent,理解:
- 要解决什么问题
- 核心设计决策
- 主要组件和边界
2. 逐维度扫描
Over-engineering 信号
检查是否存在:
- 可配置的部分 > 3 个
- 插件/扩展机制
- 多于 2 层的抽象
- "支持多种 X"的描述
- 复杂的状态机
YAGNI 信号
检查是否存在:
- "未来可能..."
- "预留..."
- "方便以后..."
- 只在"高级场景"使用的功能
- 没有具体 use case 的抽象
过早抽象信号
检查是否存在:
- 只有一个实现的接口/协议
- 只用一次的公共函数
- 只有一个子类的基类
- 不必要的工厂/策略模式
边界问题信号
检查是否存在:
- 模块间传递 > 5 个参数
- A 依赖 B,B 也依赖 A
- 一个改动需要同时改多个模块
- 职责描述模糊或重叠
3. 生成发现列表
对每个发现,准备:
- 位置:Intent 中的具体 section
- 问题:简短描述问题
- 简化建议:具体的替代方案
- 风险:简化可能带来的代价
4. 交互式讨论
对每个发现使用 AskUserQuestion:
发现 1/N: Over-engineering
Section: ## 插件系统
问题: 定义了完整的插件加载、生命周期、沙箱机制,但目前只有 2 个内置功能。
简化建议: 删除插件系统,直接硬编码这 2 个功能。
未来需要时再加。
风险: 如果很快需要第三方插件,要重新设计。
---
AskUserQuestion:
- question: "是否接受这个简化?"
- options:
- "接受简化" - 删除插件系统设计
- "保留原设计" - 请说明具体场景
- "跳过" - 暂不决定
5. 汇总报告
# Intent Critique Report
## 文件: src/core/intent/INTENT.md
## 统计
- 发现问题: 5
- 接受简化: 3
- 保留原设计: 1
- 跳过: 1
## 已接受的简化
### 1. 删除插件系统
- 原设计: 完整插件架构
- 简化为: 硬编码 2 个功能
- 影响 sections: ## 插件系统, ## 架构
### 2. 合并配置层
...
## 保留的设计
### 1. 多数据源支持
- 原因: 用户明确表示 v1.1 需要
- 建议: 在 Intent 中标注具体 timeline
## 跳过的项目
...
## 下一步
- [ ] 更新 Intent 文件(如果选择自动更新)
- [ ] 运行 /intent-validate 检查格式
- [ ] 运行 /intent-review 重新审批受影响的 sections
6. 可选:更新 Intent
如果用户同意,自动更新 Intent:
- 删除被简化掉的 sections
- 添加简化说明到变更记录
- 将受影响的 sections 标记回
draft
7. 验证净减(必须)
更新 Intent 后,立即验证:
wc -l INTENT.md
# 记录为 after_lines
判定规则:
if after_lines > before_lines:
❌ 拒绝保存。回滚更改。
报告:
before: {before_lines} lines
after: {after_lines} lines
delta: +{after_lines - before_lines} lines
"Critique must net-reduce. Review changes and remove additions."
if after_lines <= before_lines:
✅ 保存成功。
报告:
before: {before_lines} lines
after: {after_lines} lines
reduced: {before_lines - after_lines} lines ({percentage}%)
8. 保存 Critique 记录
将完整 critique 报告保存到 records/critique-{date}.md,更新 records/INDEX.md:
| 2026-02-06 | critique | — | Convergence + critique, removed §13-§15 (-180 lines), kept §2 |
记录包含:convergence 结果、devil's advocate 输出、每个发现的决策、净行数变化。
讨论技巧
提问方式
好的提问:
- "删掉 X,系统还能工作吗?"
- "有没有具体场景需要 X?"
- "X 的复杂度值得吗?"
避免:
- 预设答案
- 过于理论化的讨论
- 同时问多个不相关的问题
接受"保留"的时机
当用户提供:
- 具体的使用场景
- 明确的时间线("下月就要")
- 外部约束("合作方要求")
记录理由,建议在 Intent 中也注明。
与其他工具配合
intent-interview → intent-validate → intent-critique → intent-review
↑
可独立调用
任何时候想反思设计时
不做什么
- ❌ 不检查格式(intent-validate 的职责)
- ❌ 不检查一致性(intent-sync 的职责)
- ❌ 不标记审批状态(intent-review 的职责)
- ❌ 不自动做决定(必须与用户讨论)
Intent Init
初始化项目的 IDD (Intent Driven Development) 结构。
功能
- 检查现状 - 扫描项目,识别已有的 intent 文件或类似结构
- 创建目录 - 建立标准 IDD 目录结构
- 生成模板 - 创建入口 INTENT.md 和模块级模板
- 配置建议 - 根据项目类型给出配置建议
工作流程
/intent-init
↓
┌───────────────────────────────────┐
│ Phase 1: 扫描现状 │
│ - 查找 intent/, specs/, docs/ │
│ - 识别 README, DESIGN 等文档 │
│ - 检测项目类型 (monorepo/单模块) │
└─────────────┬─────────────────────┘
↓
┌───────────────────────────────────┐
│ Phase 2: 展示发现 │
│ - 已有文档列表 │
│ - 项目结构分析 │
│ - 推荐的 IDD 结构 │
└─────────────┬─────────────────────┘
↓
┌───────────────────────────────────┐
│ Phase 3: 确认并创建 │
│ - AskUserQuestion 确认结构 │
│ - 创建目录和模板文件 │
│ - 可选:迁移现有文档 │
└───────────────────────────────────┘
标准 IDD 目录结构
单模块项目
project/
├── intent/
│ └── INTENT.md # 项目 Intent(入口)
├── src/
└── ...
Monorepo / 多模块项目
project/
├── intent/
│ ├── INTENT.md # 项目概述(入口)
│ └── architecture/
│ ├── DEPENDENCIES.md # 模块依赖图
│ └── BOUNDARIES.md # 边界规则
│
├── src/
│ ├── module-a/
│ │ └── intent/
│ │ └── INTENT.md # 模块 Intent
│ └── module-b/
│ └── intent/
│ └── INTENT.md
└── ...
模板内容
项目级 INTENT.md
# [Project Name] Intent
> 一句话描述项目目标
状态: draft
最后更新: YYYY-MM-DD
## 愿景
[项目要解决的问题和目标]
## 架构概览
[ASCII 架构图]
## 模块索引
| 模块 | 职责 | Intent |
|------|------|--------|
| xxx | ... | [link] |
## 非目标
- [明确不做什么]
## 约束
- [技术约束]
- [业务约束]
模块级 INTENT.md
# [Module] Intent
> 模块职责一句话
状态: draft
最后更新: YYYY-MM-DD
## 职责
[模块做什么]
## 非目标
[模块不做什么]
## 数据结构
[核心数据结构定义]
## API
[对外接口定义]
## 示例
[输入 → 输出 示例]
检测逻辑
识别已有 Intent 结构
// 检查路径
const intentPaths = [
'intent/INTENT.md',
'INTENT.md',
'docs/INTENT.md',
'specs/',
'design/',
];
// 检查内容特征
const intentMarkers = [
'## 职责',
'## 非目标',
'::: locked',
'::: reviewed',
];
项目类型识别
// Monorepo 特征
const monorepoMarkers = [
'packages/',
'apps/',
'src/modules/',
'lerna.json',
'pnpm-workspace.yaml',
];
选项
/intent-init # 交互式初始化
/intent-init --dry-run # 只展示计划,不执行
/intent-init --minimal # 最小化结构
/intent-init --migrate # 尝试迁移现有文档
与其他命令配合
/intent-init # 初始化结构
↓
/intent-interview # 填充 Intent 内容
↓
/intent-review # 审批关键 sections
↓
[开发]
↓
/intent-check # 检查一致性
Intent Interview
A structured methodology for extracting, refining, and documenting product/feature requirements through deep interviewing.
Two-Phase Model
Phase A: Questioning (default)
→ Output: decisions.md (questions + user decisions)
→ Does NOT touch INTENT.md
Phase B: Compose (explicit user request)
→ Input: decisions.md
→ Output: INTENT.md (under budget constraints)
→ Checks anchor relevance + size budget
Why two phases? Interview tends to accrete — every answer becomes a new section. By separating questioning from composition, we prevent unbounded growth.
Phase A: Questioning
Goal
Collect all design decisions without writing any Intent structure. Output is a flat decisions.md file.
Process
Step 1: Problem Space (1-2 rounds)
Questions to ask:
- What is the core problem?
- Who is the target user?
- Is this a new product or addition to existing?
- What's the priority/urgency?
Step 2: Deep Dive (iterative)
Cover these dimensions systematically, 3-4 questions per round:
| Dimension | Key Questions |
|---|---|
| Data | Sources, contracts, validation, conflicts, authentication |
| Rendering | Cross-platform strategy, components, theming, sizing |
| Sync/Update | Real-time requirements, refresh strategy, failure handling |
| Architecture | Storage, sharing, cloud/local, offline capability |
| UX | Configuration flow, error states, feedback mechanisms |
| Edge Cases | Failures, migrations, security, low-end devices |
| Scope | MVP boundaries, what's in/out, phasing |
| Tech Stack | Languages, frameworks, existing code to reuse |
Step 3: Contradiction Resolution
When answers conflict with earlier choices:
- Point out the contradiction explicitly
- Ask for clarification with specific options
- Update decisions.md accordingly
Step 4: Scope Guard
Before recording each decision, check against the anchor (if established).
If a question or answer drifts from the declared purpose:
⚠️ Scope guard: This may be out of scope for:
> "Enable type-safe binary communication between AFS nodes."
Record anyway? Or defer to a separate Intent?
The anchor is established early — ask "In one sentence, what is this module's reason to exist?" in round 1.
Step 5: Readiness Check
Before moving to Phase B, verify:
- Can a code agent implement this without asking questions?
- Are all technical choices specified?
- Are edge cases covered?
If gaps exist, continue questioning.
decisions.md Output Format
# Interview Decisions: {Project/Module Name}
> Anchor: {one sentence purpose}
## Decisions
### 1. {Topic}
- **Question**: {what was asked}
- **Decision**: {what was decided}
- **Rationale**: {why}
### 2. {Topic}
...
## Open Items
- {unresolved questions}
## Out of Scope
- {items deferred by scope guard}
Question Design
Do
- Ask non-obvious, probing questions
- Probe tradeoffs ("if X fails, should we Y or Z?")
- Use concrete scenarios
- Offer 3-4 mutually exclusive options
- Match user's language (中文/English)
Don't
- Ask yes/no questions
- Ask obvious implementation details
- Ask multiple unrelated questions at once
- Add sections to INTENT.md during questioning
Format
Use AskUserQuestion tool with:
- 1-4 questions per round
- 2-4 options per question
- Short header (max 12 chars)
- Clear option descriptions
Phase B: Compose
Only runs when user explicitly requests it (e.g., "compose the intent" or "generate INTENT.md").
Process
Step 1: Read decisions.md
Parse all decisions and the anchor statement.
Step 2: Draft INTENT.md
Structure into standard Intent sections:
# {Module} Intent
> Anchor: {one sentence from decisions.md}
## Responsibilities
- {derived from decisions}
## Non-Goals
- {from "Out of Scope" + explicit exclusions}
## Structure
{architecture diagram}
## API
{interface definitions}
## Examples
{input → output}
Step 3: Anchor Relevance Check
For each section in the draft, verify:
- Can this section trace back to the anchor?
- If not, flag it:
⚠️ Section "## Caching Strategy" cannot be traced to anchor:
> "Enable type-safe binary communication between AFS nodes."
Options:
1. Remove this section
2. Move to a separate Intent
3. Keep (explain why it serves the anchor)
Step 4: Budget Check
Count the lines of the draft and check against tiered budget:
| Lines | Status | Action |
|---|---|---|
| ≤ 300 | Healthy | Save |
| 300–500 | Warning | Prompt user to trim before saving |
| > 500 | Blocked | Must trim before saving |
If over budget:
⚠️ Budget warning: 437/300 lines (+137)
Sections by size:
1. ## API — 45 lines
2. ## Structure — 38 lines
3. ## Detailed Behavior — 35 lines
...
Suggestions to reduce:
- Merge "## Error Handling" into "## API" constraints
- Move "## Migration Guide" to a separate doc
- Simplify "## Structure" diagram
Present options to user via AskUserQuestion before saving.
Step 5: Save
Write the budget-compliant INTENT.md. Optionally generate overview.md if user requests.
Output Artifacts
decisions.md (Phase A output)
Interview record with all questions, decisions, rationale, and scope boundaries.
records/interview-{date}.md (Phase A side-effect)
Raw interview transcript saved to records/ for full traceability. Updates records/INDEX.md.
intent.md (Phase B output)
Technical specification under budget constraints, with anchor-verified sections.
overview.md (optional, Phase B)
One-page human summary:
# {Project}: One-line description
## One sentence explanation
## Why?
Problem in plain language
## Core experience
ASCII flow diagram
## Architecture
ASCII component diagram
## Key decisions
| Question | Choice | Why |
## Scope
In / Out
## Risk + Mitigation
## Next steps
Workflow
User describes idea
↓
Phase A: Questioning
├── Round 1: Problem space + establish anchor
├── Round 2-N: Deep dive (with scope guard)
├── Resolve contradictions
└── Readiness check
↓
Save decisions.md
↓
User requests "compose" / "generate intent"
↓
Phase B: Compose
├── Draft from decisions
├── Anchor relevance check
├── Budget check
└── Save INTENT.md
↓
(Optional) Generate overview.md
Intent Normalize
扫描现有项目,将 intent 和 planning 文件规范化到 IDD 标准。能自动修的直接修,不能修的打上状态让 TeamSwarm pickup。
设计原则
- 格式先行 — 所有文件先有 frontmatter,让系统能识别
- 能修则修 — 机械性问题直接修复(frontmatter、目录结构、命名)
- 不能修则标记 — 内容问题打上状态,后续由 TeamSwarm 或人处理
- 幂等 — 多次运行结果一致,已规范的文件不会被改动
工作流程
/intent-normalize [path]
↓
┌───────────────────────────────────┐
│ 1. 扫描 intent/ 和 planning/ │
│ 发现所有 .md 和 .yaml 文件 │
└─────────────┬─────────────────────┘
↓
┌───────────────────────────────────┐
│ 2. 分析每个文件的合规状态 │
│ - 有无 frontmatter? │
│ - 有无 Anchor? │
│ - 目录结构是否完整? │
└─────────────┬─────────────────────┘
↓
┌───────────────────────────────────┐
│ 3. 自动修复机械问题 │
│ - 补 frontmatter │
│ - 创建 records/ + INDEX.md │
│ - 创建 _archive/, _data/ │
│ - 规范化文件命名 │
└─────────────┬─────────────────────┘
↓
┌───────────────────────────────────┐
│ 4. 标记内容问题 │
│ - 缺 Anchor → status: draft │
│ - 超预算 → 标记 needs_critique │
│ - 无法分类 → status: draft │
└─────────────┬─────────────────────┘
↓
┌───────────────────────────────────┐
│ 5. 输出规范化报告 │
└───────────────────────────────────┘
检查项与修复策略
自动修复(机械性,无需判断)
| 检查项 | 条件 | 修复动作 |
|---|---|---|
| Intent frontmatter | INTENT.md 没有 frontmatter | 添加 status: active(或根据内容推断) |
| Planning frontmatter | planning/ 下 .md 没有 frontmatter | 添加 type: (从内容推断: idea/research/feedback/analysis) |
| Anchor 格式 | Anchor 存在但格式不对(不是 blockquote) | 修正为 > Anchor: ... 格式 |
| records/ 目录 | intent 目录下没有 records/ | 创建 records/ + 空 INDEX.md |
| _archive/ 目录 | intent/ 下没有 _archive/ | 创建 intent/_archive/ |
| _data/ 目录 | intent/ 下没有 _data/ | 创建 intent/_data/ |
| TASK.yaml 格式 | TASK.yaml 缺少 type 字段 | 添加 type: one-shot(默认) |
标记 pickup(需要内容判断)
| 检查项 | 条件 | 标记动作 |
|---|---|---|
| 缺少 Anchor | INTENT.md 没有 Anchor 行 | frontmatter 加 needs: [anchor] |
| 超预算 | 行数 > 500 | frontmatter 加 needs: [critique] |
| 预算警告 | 300 < 行数 ≤ 500 | frontmatter 加 needs: [review] |
| 无 Assumes | 内容中引用了其他 intent 但没有 Assumes 标签 | frontmatter 加 needs: [assumes] |
| 分类不明 | planning 文件无法自动判断类型 | type: idea(默认最安全) |
needs 字段
needs 是 frontmatter 中的 pickup 信号,表示该文件需要后续处理:
---
status: active
needs: [anchor, critique]
---
TeamSwarm 扫描 needs 字段来自动调度后续 skill:
needs: [anchor]→ 安排/intent-interview补充needs: [critique]→ 安排/intent-critique精简needs: [review]→ 安排/intent-reviewneeds: [assumes]→ 安排人工补充依赖声明
处理完成后,对应的 needs 项被移除。needs 为空时可以删掉整个字段。
Planning 类型推断
自动从文件内容推断 type::
| 关键词/模式 | 推断类型 |
|---|---|
| idea, concept, proposal, brainstorm, what if | idea |
| research, analysis, comparison, benchmark, study | research |
| feedback, user, complaint, request, survey | feedback |
| code analysis, refactor, migration, legacy, improvement | analysis |
| 无法判断 | idea(最安全的默认值) |
执行细节
1. 扫描范围
默认扫描当前项目根目录下的:
- intent/ → 所有 INTENT.md 文件(递归,跳过 _archive/ 和 _data/)
- planning/ → 所有 .md 文件
- **/intent/ → 模块级 intent 目录
2. Frontmatter 注入
对没有 frontmatter 的文件,在文件头部插入:
Intent 文件:
---
status: active
---
如果文件看起来已经实现(有对应的代码目录和测试),推断为:
---
status: implemented
---
Planning 文件:
---
type: research
---
3. 推断 status 的启发式规则
| 信号 | 推断 status |
|---|---|
| 有 TASK.yaml 且 status: done | implemented |
| 有对应的 src/ 目录且文件最近没修改 | implemented |
| 文件内容很少(< 50 行)或明显不完整 | active(+ needs: [anchor]) |
| 默认 | active |
4. 幂等保证
- 已有正确 frontmatter 的文件不修改
- 已有 records/ 的不重建
needs字段只添加不覆盖(合并已有的)- 每次运行结果相同
输出
规范化报告
# Intent Normalize Report
> 项目: my-project
> 扫描时间: 2026-02-06
## 统计
| 类型 | 扫描 | 已规范 | 自动修复 | 需 pickup |
|------|------|--------|----------|-----------|
| Intent 文件 | 15 | 8 | 5 | 2 |
| Planning 文件 | 7 | 2 | 4 | 1 |
| 目录结构 | — | — | 3 | — |
## 自动修复(已完成)
1. ✅ `intent/kernel/proc/INTENT.md` — 添加 frontmatter `status: active`
2. ✅ `intent/kernel/afs/INTENT.md` — 添加 frontmatter `status: implemented`
3. ✅ `planning/v2-ideas.md` — 添加 frontmatter `type: idea`
4. ✅ `planning/legacy-analysis.md` — 添加 frontmatter `type: analysis`
5. ✅ `intent/kernel/proc/records/` — 创建目录 + INDEX.md
6. ✅ `intent/_archive/` — 创建目录
7. ✅ `intent/_data/` — 创建目录
## 需要 Pickup(已标记)
| 文件 | needs | 建议 |
|------|-------|------|
| `intent/ash/INTENT.md` | `[anchor, critique]` | 缺少 Anchor,612 行超预算 |
| `intent/surfaces/INTENT.md` | `[anchor]` | 缺少 Anchor |
| `planning/random-notes.md` | — | 无法分类,默认 type: idea |
使用
基本用法
/intent-normalize
扫描并规范化当前项目。
指定路径
/intent-normalize intent/kernel/
只规范化特定目录。
Dry run
/intent-normalize --dry-run
只报告,不做任何修改。
与其他命令配合
/intent-normalize # 先规范化格式(本命令)
↓
TeamSwarm pickup # 自动调度 needs 中的后续 skill
↓
/intent-interview # 处理 needs: [anchor]
/intent-critique # 处理 needs: [critique]
/intent-review # 处理 needs: [review]
↓
/intent-check # 最终合规检查
Intent Plan
Transform an approved Intent into a structured, executable development plan with strict TDD discipline.
Output is TaskSwarm-compatible: The generated plan.md can be directly executed by /swarm run.
Core Principles
- Test First, Always: Every implementation step starts with writing tests
- Phased Execution: Break work into phases with clear deliverables (0-indexed)
- Verification Gates: Each phase ends with e2e validation
- Automation Priority: Prefer CLI/script testing over manual/browser testing
- Checkbox Tracking: All tests use
- [ ]format for progress tracking
Plan Structure
## Phase 0: [Phase Name]
├── ### Description
├── ### Tests
│ ├── #### Happy Path
│ │ └── - [ ] test case 1
│ ├── #### Bad Path (详尽列举)
│ │ └── - [ ] error case 1
│ ├── #### Edge Cases
│ │ └── - [ ] boundary case 1
│ ├── #### Security
│ │ └── - [ ] vulnerability test 1
│ ├── #### Data Leak
│ │ └── - [ ] leak prevention test 1
│ └── #### Data Damage
│ └── - [ ] integrity test 1
├── ### E2E Gate
│ └── CLI/Script 验证命令
└── ### Acceptance Criteria
└── - [ ] criterion 1
## Phase 1: [Phase Name]
└── ...
Test Categories (6 Required)
Every phase MUST include tests from ALL 6 categories:
| Category | Description | Examples |
|---|---|---|
| Happy Path | Normal expected usage | Valid inputs, correct sequences |
| Bad Path | Invalid inputs, error conditions | Wrong types, missing required fields, invalid states |
| Edge Cases | Boundary conditions | Empty inputs, max values, concurrent access |
| Security | Vulnerability prevention | Injection attacks, auth bypass, privilege escalation |
| Data Leak | Information exposure | Sensitive data in logs, error messages, API responses |
| Data Damage | Data integrity protection | Partial writes, corruption, race conditions |
Bad cases must be detailed and comprehensive. A good test suite has more failure tests than success tests.
Test Writing Discipline
- Tests First: Write ALL tests before any implementation
- Red-Green-Refactor: Run tests expecting failure, implement, verify pass
- No Skip: Every category must have at least one test case
Phase Gates: E2E Verification (Required)
Each phase MUST end with E2E verification. This is the gate that proves the phase is truly complete.
E2E Gate Requirements
- Automatable: Must be runnable via CLI/script, no manual steps
- Independent: Can run without human intervention
- Reproducible: Same inputs produce same outputs
- Fast Feedback: Fails quickly when something is wrong
Preferred: CLI/Script Testing
# Example: API verification
curl -X POST http://localhost:3000/api/resource \
-H "Content-Type: application/json" \
-d '{"field": "value"}' | jq .
# Example: Database state check
psql -c "SELECT * FROM table WHERE condition"
# Example: File system verification
diff expected_output.json actual_output.json
# Example: Unit test suite
pnpm test -- --coverage
For Web Projects: Automation-Friendly Design
DO:
- Provide health check endpoints
- Return machine-parseable responses (JSON)
- Include test mode / seed data endpoints
- Design idempotent operations
DON'T:
- Require browser interaction for verification
- Depend on visual inspection
- Need manual clicking through UI
When Browser Testing is Unavoidable
If browser/headless testing is truly necessary:
- Use Playwright/Puppeteer with script automation
- Create dedicated test endpoints
- Prefer API calls over UI interaction
Pre-Plan Gates (Mandatory)
Before generating any plan, ALL gates must pass. No exceptions.
/intent-plan
↓
┌─────────────────────────────────────┐
│ Gate 1: Interview Check │
│ ✗ → "先跑 /intent-interview" │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Gate 2: Critique Check │
│ ✗ → "先跑 /intent-critique" │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Gate 3: Dependency Check │
│ ✗ → "前置任务未完成,无法 plan" │
└─────────────────────────────────────┘
↓
✓ All gates passed → Generate plan.md
Gate 1: Interview Check
Verify the Intent has been properly interviewed:
| Check | How to Verify | If Failed |
|---|---|---|
| INTENT.md exists | File exists in intent directory | Run /intent-interview |
| Anchor exists | First blockquote after title starts with > | Add anchor statement |
| Within budget | wc -l INTENT.md ≤ 500 (warning at 300) | Run /intent-critique to reduce if > 500 |
| Structure complete | Has Responsibilities, Structure, API sections | Run /intent-interview |
| Not a stub | Content is substantial, not placeholder text | Run /intent-interview |
Output if failed:
❌ Gate 1 Failed: Interview Incomplete
INTENT.md is missing or incomplete:
- [ ] Responsibilities section missing
- [ ] Structure diagram missing
Action required: Run /intent-interview first.
Gate 2: Critique Check
Verify the Intent has been critiqued for over-engineering:
| Check | How to Verify | If Failed |
|---|---|---|
| Critique done | Look for critique markers or changelog | Run /intent-critique |
| Post-modification | If INTENT.md modified after last critique | Run /intent-critique again |
| AI assessment | Ask AI if another critique round is needed | Run /intent-critique if yes |
Critique markers to look for:
<!-- critique: {date} -->comment in INTENT.mdcritique.mdorCRITIQUE.mdin same directory- Changelog entry mentioning critique
Post-modification detection:
- Compare INTENT.md mtime with critique marker date
- If INTENT.md is newer AND has substantial changes → re-critique required
AI Assessment prompt:
"Based on this Intent, is there any sign of over-engineering, premature abstraction, or YAGNI violation that warrants another critique round?"
Output if failed:
❌ Gate 2 Failed: Critique Required
Intent has not been critiqued, or was modified after critique:
- Last critique: 2026-01-15
- INTENT.md modified: 2026-01-20 (substantial changes detected)
Action required: Run /intent-critique to review for over-engineering.
Gate 3: Dependency Check
Verify all prerequisites are satisfied:
| Check | How to Verify | If Failed |
|---|---|---|
| Internal deps | Referenced intents have status: done in TASK.yaml | List blocking intents |
| External deps | Required packages/services exist | List missing dependencies |
| Environment | Required env vars, credentials, access | List missing setup |
How to find dependencies:
- Parse
## Prerequisitesor## Dependenciesin INTENT.md - Look for
depends_on:in TASK.yaml (if exists) - Scan for references like
intent/other-feature/or@package/name
Dependency states:
intent/auth/ → TASK.yaml status: done ✓ OK
intent/database/ → TASK.yaml status: review ✗ Blocked (not done)
intent/api/ → No TASK.yaml ? Assume not started
@aigne/afs → Check packages/ or deps ✓/✗
Output if failed:
❌ Gate 3 Failed: Dependencies Not Ready
This Intent cannot be planned because prerequisites are incomplete:
Blocking Intents:
- intent/auth-module/ → status: in_progress (need: done)
- intent/database-setup/ → status: ready (need: done)
Missing External Dependencies:
- @aigne/session-protocol → not found in packages/
Action required: Complete blocking tasks first, or remove dependencies from INTENT.md if not actually needed.
Gate Pass Output
When all gates pass:
✓ Gate 1: Interview complete
✓ Gate 2: Critique done (2026-01-20), no re-critique needed
✓ Gate 3: All 2 dependencies satisfied
Proceeding to generate plan...
Workflow
/intent-plan
↓
Gate 1: Interview Check ──→ ✗ → Stop, require /intent-interview
↓ ✓
Gate 2: Critique Check ───→ ✗ → Stop, require /intent-critique
↓ ✓
Gate 3: Dependency Check ─→ ✗ → Stop, list blockers
↓ ✓
Read Intent file
↓
Analyze scope and complexity
↓
Identify logical phases (0-indexed)
↓
For each phase, define:
- Description
- Tests (6 categories)
- E2E Gate
- Acceptance Criteria
↓
Present plan for approval
↓
User confirms or adjusts
↓
Save to plan.md (same directory as INTENT.md)
↓
Create TASK.yaml (status: ready)
Output Files
1. plan.md (Required)
# Execution Plan: {task_name}
## Overview
简要说明这个任务要做什么。
## Prerequisites
- 前置条件
- 依赖的其他任务
- 需要的权限或资源
## Phase 0: {Phase Name}
### Description
这个阶段要完成什么,交付什么。
### Tests
#### Happy Path
- [ ] 测试正常流程 1: {具体描述}
- [ ] 测试正常流程 2: {具体描述}
#### Bad Path
- [ ] 无效输入: {具体场景}
- [ ] 缺失必填字段: {具体场景}
- [ ] 错误状态: {具体场景}
- [ ] 类型错误: {具体场景}
#### Edge Cases
- [ ] 空输入处理
- [ ] 最大值边界
- [ ] 并发访问
#### Security
- [ ] 注入攻击防护: {具体场景}
- [ ] 权限绕过防护: {具体场景}
- [ ] 输入验证: {具体场景}
#### Data Leak
- [ ] 错误信息不泄露敏感数据
- [ ] 日志不包含敏感信息
- [ ] API 响应不过度暴露
#### Data Damage
- [ ] 部分写入恢复
- [ ] 竞态条件处理
- [ ] 事务完整性
### E2E Gate
```bash
# Phase 完成验证脚本
{CLI commands to verify phase completion}
Acceptance Criteria
- 所有 6 类测试通过
- E2E Gate 验证通过
- 代码已提交并 push
Phase 1: {Phase Name}
Description
下一阶段要完成什么。
Tests
Happy Path
- 测试正常流程
Bad Path
- 测试错误处理 1
- 测试错误处理 2
Edge Cases
- 边界条件处理
Security
- 安全测试
Data Leak
- 泄露防护测试
Data Damage
- 数据完整性测试
E2E Gate
# Phase 1 验证脚本
Acceptance Criteria
- 所有测试通过
- E2E Gate 验证通过
Final E2E Verification
# 全系统端到端验证脚本
# 验证所有 Phase 的功能协同工作
Risk Mitigation
| Risk | Mitigation | Contingency |
|---|---|---|
| [风险 1] | [预防措施] | [发生时的应对] |
References
### 2. TASK.yaml (Required)
```yaml
status: ready
owner: null
assignee: null
phase: 0/{total_phases}
updated: {UTC_ISO_TIMESTAMP}
heartbeat: null
Important: {total_phases} is the number of phases in plan.md (0-indexed counting).
Integration with IDD & TaskSwarm
IDD Flow:
/intent-interview # Create Intent (Gate 1 requirement)
↓
/intent-critique # Review for over-engineering (Gate 2 requirement)
↓
/intent-review # Approve Intent (optional but recommended)
↓
/intent-plan # Gate checks → Generate plan.md + TASK.yaml (THIS SKILL)
↓
TaskSwarm Flow:
/swarm run # Execute plan (TDD cycles)
↓
/swarm approve # Human review
↓
/intent-sync # Write back confirmed details
Gate enforcement ensures quality:
- No plan without proper interview → avoids vague/incomplete specs
- No plan without critique → avoids over-engineered designs
- No plan with missing deps → avoids unexecutable plans
Tips for Good Plans
Format (TaskSwarm Compatible)
- 0-indexed phases: Phase 0, Phase 1, Phase 2...
- Checkbox format: All tests use
- [ ]for progress tracking - E2E Gate per phase: Each phase must have runnable verification
Test Quality
- All 6 categories required: Happy/Bad/Edge/Security/Data Leak/Data Damage
- Bad Path > Happy Path: More failure tests than success tests
- Specific test cases: "Test error handling" ✗ → "returns 404 when resource not found" ✓
- Security by default: Include even if not explicitly requested
Phase Design
- Right-size phases: Each phase completable in 1-3 days
- Clear dependencies: Note when phases depend on previous phases
- Automatable gates: E2E Gate must be runnable via CLI, no manual steps
Example: Complete Output
For an Intent at intent/session-protocol/INTENT.md:
Creates: intent/session-protocol/plan.md
# Execution Plan: session-protocol
## Overview
实现 Session Protocol 的 Frame 编解码功能。
## Prerequisites
- @aigne/afs 包已存在
- TypeScript 环境配置完成
## Phase 0: Frame Encoding
### Description
实现 Frame 的编码函数,将结构化数据转换为二进制格式。
### Tests
#### Happy Path
- [ ] encodes empty frame correctly
- [ ] encodes frame with JSON payload
- [ ] encodes frame with binary payload
- [ ] preserves ReqId across encode/decode
#### Bad Path
- [ ] throws on invalid frame type
- [ ] throws on payload exceeding max size
- [ ] throws on null payload when required
- [ ] throws on negative ReqId
- [ ] throws on non-integer frame type
#### Edge Cases
- [ ] handles empty string payload
- [ ] handles maximum allowed payload size (64KB)
- [ ] handles unicode in JSON payload
- [ ] handles zero-length binary payload
#### Security
- [ ] rejects frames with potential injection patterns
- [ ] validates frame type bounds (0-255)
- [ ] sanitizes string inputs before encoding
#### Data Leak
- [ ] error messages don't expose internal structure
- [ ] stack traces not included in thrown errors
#### Data Damage
- [ ] atomic write: partial encode doesn't corrupt buffer
- [ ] buffer overflow protection
### E2E Gate
```bash
# Verify encoding works end-to-end
pnpm test -- --grep "Frame Encoding"
pnpm test:e2e -- --grep "encode"
Acceptance Criteria
- 所有 6 类测试通过
- E2E Gate 验证通过
- 100% 分支覆盖率
- 代码已提交
Phase 1: Frame Decoding
Description
实现 Frame 的解码函数,将二进制数据解析为结构化对象。
Tests
Happy Path
- decodes valid frame correctly
- handles streaming decode
- decodes all frame types
Bad Path
- throws on truncated frame
- throws on corrupted header
- throws on invalid magic bytes
- throws on unsupported version
Edge Cases
- handles minimum valid frame
- handles maximum valid frame
- handles back-to-back frames in stream
Security
- validates frame length before allocation
- rejects oversized frames (DoS protection)
Data Leak
- doesn't expose raw bytes in error messages
Data Damage
- partial decode doesn't advance stream position
- corrupted frame doesn't affect subsequent frames
E2E Gate
# Verify full roundtrip
pnpm test -- --grep "Frame"
echo '{"test":1}' | node scripts/encode-decode-test.js
Acceptance Criteria
- 所有测试通过
- E2E roundtrip 验证通过
- 代码已提交
Final E2E Verification
# Full integration test
pnpm test
pnpm test:e2e
References
**Creates**: `intent/session-protocol/TASK.yaml`
```yaml
status: ready
owner: null
assignee: null
phase: 0/2
updated: 2026-01-27T10:00:00Z
heartbeat: null
Intent Report
将技术性的 Intent 文件转换成人类可读的报告文档。
用途
- 给 Stakeholder:项目概览、进度、关键决策
- 给新成员:快速了解项目架构和设计理由
- 给文档:生成 README、设计文档、架构说明
- 给会议:项目汇报、技术评审
工作流程
/intent-report [options]
↓
┌───────────────────────────────────┐
│ 读取 Intent 文件 │
│ - 项目级 + 模块级 │
│ - 解析结构和元数据 │
└─────────────┬─────────────────────┘
↓
┌───────────────────────────────────┐
│ 确定报告类型 │
│ - overview / architecture / │
│ progress / full │
└─────────────┬─────────────────────┘
↓
┌───────────────────────────────────┐
│ 生成报告 │
│ - 重组内容结构 │
│ - 转换技术语言 │
│ - 添加可视化 │
└─────────────┬─────────────────────┘
↓
┌───────────────────────────────────┐
│ 输出 │
│ - Markdown / HTML / PDF │
│ - 写入文件 or 直接展示 │
└───────────────────────────────────┘
报告类型
1. Overview (概览)
/intent-report --type overview
一页纸项目概览,适合快速了解:
# [Project] Overview
## What is this?
[一句话说明]
## Problem
[要解决的问题]
## Solution
[解决方案概述]
## Architecture
[简化的架构图]
## Key Modules
| Module | Purpose |
|--------|---------|
## Status
[当前状态和下一步]
2. Architecture (架构)
/intent-report --type architecture
详细架构文档,适合技术评审:
# [Project] Architecture
## System Overview
[架构图]
## Module Dependencies
[依赖关系图]
## Data Flow
[数据流图]
## Key Design Decisions
| Decision | Choice | Rationale |
## Boundary Rules
[模块边界规则]
## API Reference
[核心 API 列表]
3. Progress (进度)
/intent-report --type progress
项目进度报告,适合汇报:
# [Project] Progress Report
> Generated: YYYY-MM-DD
## Intent Coverage
[覆盖率图表]
## Module Status
| Module | Intent | Impl | Status |
|--------|--------|------|--------|
| core | ✓ | 80% | 🟡 |
## Recent Updates
[最近的 Intent 变更]
## Approval Status
- Locked: N sections
- Reviewed: M sections
- Draft: K sections
## Blockers & Risks
[风险和阻塞项]
## Next Steps
[下一步计划]
4. Full (完整)
/intent-report --type full
完整技术文档,包含所有内容。
输出格式
Markdown (默认)
/intent-report -o report.md
HTML
/intent-report --format html -o report.html
带样式的 HTML 文档,可直接在浏览器查看。
Console (直接显示)
/intent-report
不指定输出文件时,直接在终端展示。
使用示例
生成项目概览
/intent-report --type overview
生成架构文档给新成员
/intent-report --type architecture -o docs/ARCHITECTURE.md
生成进度报告给 stakeholder
/intent-report --type progress -o reports/progress-2026-01.md
生成单模块报告
/intent-report src/core/ --type full
内容转换规则
技术语言 → 人类语言
| Intent 中 | 报告中 |
|---|---|
## 职责 | "What this module does" |
## 非目标 | "Out of scope" |
## 约束 | "Constraints & Rules" |
::: locked | "Core Architecture (frozen)" |
::: reviewed | "Approved Design" |
::: draft | "Work in Progress" |
ASCII 图 → 可视化
- 保留 ASCII 图(兼容性好)
- 可选:转换为 Mermaid 图(
--mermaid选项)
与其他命令配合
/intent-init # 初始化
↓
/intent-interview # 创建 Intent
↓
/intent-review # 审批
↓
/intent-report # ← 生成报告(本命令)
↓
分享给 stakeholder / 团队
高级选项
/intent-report
--type <type> # overview | architecture | progress | full
--format <format> # markdown | html
--output <path> # 输出文件路径
--module <path> # 指定模块
--include-draft # 包含 draft sections
--mermaid # 转换为 Mermaid 图
--lang <lang> # 输出语言 (en | zh)
Intent Review
交互式 Section 级别的 Intent 审批工具。
核心概念
Intent 文档按 Section 粒度审批,三种状态:
| 状态 | 标记 | 含义 | Agent 行为 |
|---|---|---|---|
| LOCKED | ::: locked | 核心架构,修改需 human 明确同意 | 暂停,请求确认 |
| REVIEWED | ::: reviewed | 已审阅,可修改但需通知 | 允许,事后通知 |
| DRAFT | ::: draft | 草稿,可自由迭代 | 自由修改 |
工作流程
/intent-review [path]
↓
┌───────────────────┐
│ 解析 Intent 文件 │
│ 识别所有 Section │
└─────────┬─────────┘
↓
┌───────────────────┐
│ 展示状态概览 │
│ N locked │
│ M reviewed │
│ K draft/unmarked │
└─────────┬─────────┘
↓
┌───────────────────────────────────────┐
│ 逐个未标记 Section 询问 │
│ │
│ AskUserQuestion: │
│ "Section: [标题]" │
│ 选项: │
│ - Lock (核心架构) │
│ - Review (确认接受) │
│ - Skip (保持 draft) │
└─────────┬─────────────────────────────┘
↓
┌───────────────────┐
│ 更新文件 │
│ 添加标记和属性 │
└───────────────────┘
使用方法
审批指定文件
/intent-review src/core/intent/INTENT.md
审批当前模块
cd src/chambers/terminal
/intent-review
自动查找 intent/INTENT.md
批量审批
/intent-review --all
扫描项目所有 intent 文件
执行步骤
1. 定位 Intent 文件
// 优先级:
// 1. 用户指定路径
// 2. 当前目录下 intent/INTENT.md
// 3. 当前目录下 INTENT.md
2. 解析 Section
识别两种 Section:
已标记的:
::: locked
## 模块边界
...
:::
未标记的(普通 markdown heading):
## API 设计
...
3. 展示概览
Intent Review: src/core/intent/INTENT.md
状态概览:
├── 🔒 LOCKED: 2 sections
│ ├── 模块边界规则
│ └── 数据结构
├── ✓ REVIEWED: 3 sections
│ ├── API 签名 (by robert, 2026-01-19)
│ ├── 配置格式
│ └── 错误处理
└── 📝 UNMARKED: 4 sections
├── 实现建议
├── 性能考虑
├── 示例代码
└── 变更记录
是否开始审批未标记的 sections?
4. 逐个审批
对每个未标记 Section 使用 AskUserQuestion:
使用 AskUserQuestion:
- question: "Section: API 签名\n\n内容预览:定义了 create(), delete(), list() 三个函数..."
- header: "审批状态"
- options:
- label: "Lock (核心架构)"
description: "锁定此 section,修改需要 human 明确同意"
- label: "Review (确认接受)"
description: "标记为已审阅,Agent 可修改但需通知"
- label: "Skip (保持 draft)"
description: "暂不审批,保持草稿状态"
5. 更新文件
根据用户选择,在 markdown 中添加标记:
Lock 选择:
::: locked {reason="核心架构"}
## API 签名
...
:::
Review 选择:
::: reviewed {by=<username> date=<today>}
## API 签名
...
:::
Skip 选择: 不修改,或添加:
::: draft
## 实现建议
...
:::
特殊场景
检测 LOCKED Section 被修改
当文件有未提交的修改时:
⚠️ 检测到 LOCKED section 被修改:
- Section: 模块边界规则
- 修改内容: [diff preview]
此修改需要 human 明确同意。是否接受?
查看审批历史
/intent-review --history src/core/intent/INTENT.md
输出:
Section: API 签名
├── 2026-01-19 robert: reviewed
├── 2026-01-15 robert: draft → reviewed
└── 2026-01-10 created
Section: 模块边界
├── 2026-01-18 robert: locked (reason: 核心架构)
└── 2026-01-12 created
与其他工具配合
intent-interview → 创建 Intent (默认全是 draft)
↓
/intent-review → 审批关键 sections
↓
aine-dev-flow → 开发实现 (遵守 locked/reviewed 规则)
↓
intent-sync → 检查一致性
配置
可在 ~/.claude/settings.json 中配置默认 reviewer:
{
"idd": {
"reviewer": "robert",
"autoLockPatterns": ["模块边界", "数据结构", "安全约束"]
}
}
Intent Story
通过采访式对话,帮助用户分享 IDD (Intent Driven Development) 的采用经验,生成传播 IDD 方法论的博客文章。
核心理念
- 采访式创作:AI 分析 + 提问 + 用户回答 + AI 按风格整合
- 真实故事:基于用户真实经验,不编造案例
- 传播 IDD:每篇文章都自然介绍 IDD 理念和工具
Workflow
/intent-story
↓
┌───────────────────────────────────┐
│ Phase 1: 背景分析 │
│ - 检测输入语言 │
│ - 加载写作风格(如有) │
│ - 了解用户 IDD 使用背景 │
└─────────────┬─────────────────────┘
↓
┌───────────────────────────────────┐
│ Phase 2: 结构化采访 │
│ - 采用经历 │
│ - 关键转折/教训 │
│ - 具体收益/数据 │
│ - 建议和反思 │
└─────────────┬─────────────────────┘
↓
┌───────────────────────────────────┐
│ Phase 3: 确认输出需求 │
│ - 文章格式/风格/长度 │
│ - 目标语言版本 │
└─────────────┬─────────────────────┘
↓
┌───────────────────────────────────┐
│ Phase 4: 生成文章 │
│ - 完整博客 + 社交媒体版 │
│ - 多语言版本(按需) │
│ - 自然融入 IDD 介绍 │
└───────────────────────────────────┘
Phase 1: 背景分析
语言检测
- 根据用户输入的主要语言确定初始写作语言
- 后续可询问是否需要其他语言版本
写作风格加载
按优先级加载(如存在):
~/.claude/content-profile/writing-style.md(用户自定义)- 使用本技能默认风格
初始问题
使用 AskUserQuestion 了解背景:
question: "你是在什么类型的项目中使用 IDD 的?"
header: "项目类型"
options:
- label: "系统软件/框架"
description: "框架、库、基础设施等"
- label: "Web 应用"
description: "前端或全栈 Web 项目"
- label: "移动应用"
description: "iOS、Android 或跨平台"
- label: "其他"
description: "其他类型项目"
Phase 2: 结构化采访
采访维度
每轮 2-3 个问题,通常 3-5 轮完成。
1. 采用动机
"是什么让你开始尝试 IDD?"
- A) 文档总是过时,想找更好的方法
- B) AI 辅助开发需要更好的上下文管理
- C) 团队协作需要更清晰的设计契约
- D) 其他原因
2. 转折时刻
"使用 IDD 过程中,有没有一个'啊哈'时刻让你觉得值得?"
[开放式,收集故事]
3. 具体收益
"你观察到的最明显的改变是什么?"
- A) AI 代码质量提升(更少需要修改)
- B) 架构边界更清晰
- C) 文档不再过时
- D) 新人上手更快
- E) 其他
"能否量化一下收益?(可选)"
[开放式,如:"AI 一次生成可用代码的比例从 30% 提升到 70%"]
4. 教训和挑战
"遇到过什么挑战或走过的弯路?"
[开放式]
"如果重新开始,你会有什么不同的做法?"
[开放式]
5. 给其他人的建议
"对考虑采用 IDD 的人,你有什么建议?"
[开放式]
采访原则
- 少问多推:能从上文推断的不重复问
- 故事优先:鼓励用户分享具体经历
- 真实性:不编造案例,用户没有的就不加
- 深度追问:对有价值的回答继续挖掘
Phase 3: 确认输出需求
采访完成后,确认输出格式:
文章风格
question: "这篇文章的风格?"
header: "风格"
options:
- label: "技术分享"
description: "peer-to-peer,工程师视角"
- label: "经验总结"
description: "回顾反思,Founder/Lead 视角"
- label: "入门指南"
description: "帮助新人理解和上手"
- label: "案例研究"
description: "详细的项目案例分析"
文章长度
question: "目标长度?"
header: "长度"
options:
- label: "短文 (800-1200字)"
description: "快速阅读,重点突出"
- label: "中等 (1500-2500字)"
description: "有深度的分享"
- label: "长文 (3000+字)"
description: "完整详细的案例分析"
语言版本
question: "需要生成哪些语言版本?"
header: "语言"
multiSelect: true
options:
- label: "中文"
description: "简体中文版本"
- label: "English"
description: "English version"
- label: "两者都要"
description: "中英双语"
Phase 4: 生成文章
文章结构
# [标题:吸引人的 IDD 经验标题]
[开头:核心洞察/结论,吸引读者]
## 背景/起因
[为什么开始使用 IDD]
## 关键发现/转折
[使用过程中的洞察和故事]
## 实际收益
[具体的改变和量化数据]
## 教训和建议
[给其他人的建议]
## 结语
[总结 + IDD 介绍]
---
## 关于 IDD
[IDD 简介和工具链,见下文模板]
IDD 介绍模板(必须包含)
每篇文章结尾自然融入:
---
## About IDD (Intent Driven Development)
IDD 是一种以 Intent(意图)为核心的开发方法论:
Intent → Test → Code → Sync
**核心理念**:Intent 是新的源代码。Code review 由 AI 完成,Intent review 由 Human 完成。
**工具链**:
- `/intent-assess` - 评估项目是否适合 IDD
- `/intent-init` - 初始化 IDD 结构
- `/intent-interview` - 从想法创建 Intent
- `/intent-check` - 验证代码与 Intent 一致性
**开始使用**:
```bash
npx add-skill arcblock/idd
### 社交媒体版本
同时生成 Twitter/X 版本:
[核心洞察,1-2句]
[关键数据/收益]
[一句话 CTA]
🔗 [文章链接]
#IntentDrivenDevelopment #IDD #AIEngineering
### 写作风格指南
遵循以下原则(来自用户写作风格):
| 原则 | 说明 |
|------|------|
| 观点鲜明 | 不做骑墙派,有明确立场 |
| 真实案例 | 故事来自用户,不编造 |
| 段落充实 | 每段 4-8 句,有完整论述 |
| 小标题精简 | 2-4 个小标题,内容丰富 |
| 内省式表达 | "我觉得..."而非"你应该..." |
| 避免套话 | 每个观点要有具体洞察支撑 |
| 禁用 em dash | 用 "-" 或 "," 替代 "—" |
## 输出示例
```markdown
# 从「文档总是过时」到「Intent 就是代码」- 我的 IDD 实践
半年前,我们团队面临一个经典困境:文档写得再好,三周后就过时...
[正文...]
---
## About IDD
IDD (Intent Driven Development) 是一种以意图为核心的开发方法论...
[工具链介绍...]
**开始使用**:
\`\`\`bash
git clone https://github.com/ArcBlock/idd
claude mcp add-plugin ~/path/to/idd
\`\`\`
与其他命令配合
[用户使用 IDD 一段时间]
↓
/intent-story # 分享经验,生成博客
↓
发布博客 / 社交媒体
↓
传播 IDD 方法论
注意事项
- 真实性:所有案例和数据必须来自用户,不能编造
- 自然融入:IDD 介绍要自然融入结尾,不是生硬广告
- 用户语言:主要语言跟随用户输入
- 风格一致:如有用户写作风格配置,优先使用
Intent Sync
Synchronize implementation details back to Intent after development is complete. This makes Intent the true single source of truth.
When to Use
Use /intent-sync when:
- Implementation is complete
- All tests pass
- User has confirmed the implementation works
- You want to capture the finalized design in Intent
What Gets Synced Back
During implementation, many details get finalized that weren't specified in the original Intent:
| Category | Examples |
|---|---|
| Interfaces | API endpoints, function signatures, protocol definitions |
| Data Structures | Schema definitions, type definitions, model structures |
| Naming | Final class names, function names, variable conventions |
| Architecture | Module boundaries, dependency directions, layer structure |
| Configuration | Environment variables, config file formats, defaults |
| Error Handling | Error codes, error message formats, recovery strategies |
Workflow
User confirms implementation is done
↓
Read original Intent file
↓
Scan implemented code for:
- Public interfaces
- Data structures
- Key naming conventions
- Architecture patterns
↓
Compare with Intent
↓
Identify gaps/differences
↓
Present changes for approval
↓
Update Intent with confirmed details
↓
Mark synced sections with timestamp
Sync Process
Step 1: Gather Implementation Facts
Scan the codebase for finalized details:
Code Analysis:
├── Public APIs
│ ├── Endpoints (REST/GraphQL/RPC)
│ ├── Function signatures
│ └── Event definitions
├── Data Models
│ ├── Database schemas
│ ├── Type definitions
│ └── Config structures
├── Architecture
│ ├── Module structure
│ ├── Dependency graph
│ └── Layer boundaries
└── Conventions
├── Naming patterns
├── Error formats
└── Logging standards
Step 2: Compare with Intent
Identify what's new or different:
| Status | Meaning | Action |
|---|---|---|
| New | Not in original Intent | Add to Intent |
| Changed | Different from Intent | Update Intent |
| Confirmed | Matches Intent | Mark as implemented |
| Removed | In Intent but not implemented | Remove or mark deferred |
Step 3: Present for Approval
Use AskUserQuestion to confirm changes:
"The following details were finalized during implementation.
Should I sync them back to Intent?"
Interfaces:
- [x] POST /api/users - Create user (new)
- [x] UserSchema: added 'createdAt' field (changed)
Data Structures:
- [x] Config now uses YAML instead of JSON (changed)
Naming:
- [x] Service class renamed to UserService (changed)
Step 4: Update Intent
Add a new section or update existing sections:
## Finalized Implementation Details
> Synced on: YYYY-MM-DD
> From: [commit hash or version]
### API Interfaces
| Endpoint | Method | Request | Response |
|----------|--------|---------|----------|
| /api/users | POST | `{name, email}` | `{id, name, email, createdAt}` |
| /api/users/:id | GET | - | `{id, name, email, createdAt}` |
### Data Structures
\`\`\`typescript
interface User {
id: string;
name: string;
email: string;
createdAt: Date;
}
\`\`\`
### Module Structure
\`\`\`
src/
├── api/
│ └── users.ts # User endpoints
├── services/
│ └── UserService.ts # Business logic
├── models/
│ └── User.ts # Data model
└── config/
└── config.yaml # Configuration
\`\`\`
### Key Decisions Confirmed
| Decision | Final Choice | Rationale |
|----------|--------------|-----------|
| Config format | YAML | Better readability for nested config |
| ID generation | UUID v4 | Standard, no coordination needed |
Output Format
The sync adds or updates these Intent sections:
New Section: ## Finalized Implementation Details
Contains:
- Sync timestamp
- Source reference (commit/version)
- Concrete interfaces
- Concrete data structures
- Final module structure
- Confirmed decisions
Updated Existing Sections
- Architecture diagrams updated to reflect reality
- Data contracts updated with actual schemas
- API specifications updated with real endpoints
Sync Markers
Use markers to indicate sync status:
## API Design
> [!SYNCED] Last synced: 2024-01-15 from commit abc123
### Endpoints
...
Or in tables:
| Component | Status | Last Synced |
|---|---|---|
| User API | SYNCED | 2024-01-15 |
| Auth API | DRAFT | - |
Integration with Other Skills
/intent-interview # Create Intent (initial)
↓
/intent-review # Approve Intent
↓
/intent-plan # Generate execution plan
↓
[Execute: TDD cycles]
↓
/intent-sync # Write back confirmed details (THIS SKILL)
↓
/intent-check # Verify consistency
Best Practices
- Sync after stability: Don't sync during active development; wait for confirmation
- Preserve original intent: Keep original design rationale, add implementation details
- Be specific: Include actual types, actual endpoints, actual names
- Version reference: Always note which code version was synced
- Incremental sync: Can sync multiple times as features stabilize
Example Session
User: Implementation is done, tests pass. Please sync back to Intent.
Agents 4
Deprecated Agents
These agents are deprecated as of 2026-01. Their capabilities have been absorbed into the plan.md format.
Why Deprecated
The IDD workflow has evolved:
Before: Runtime agents generated tests and orchestrated execution
/intent-build-now
→ idd-task-execution-master (分解 phases)
→ idd-test-master (生成测试)
→ idd-code-guru (实现代码)
→ idd-e2e-test-queen (E2E 测试)
After: plan.md contains complete test matrix, TaskSwarm executes
/intent-plan
→ Generates plan.md (complete test matrix)
→ Generates TASK.yaml (status tracking)
/swarm run
→ Executes TDD phases directly from plan.md
→ No intermediate agents needed
Migration
| Old Agent | Replacement |
|---|---|
idd-task-execution-master | plan.md Phase structure |
idd-test-master | plan.md 6-category test matrix |
idd-code-guru | Claude direct execution |
idd-e2e-test-queen | plan.md E2E Gate sections |
Safe to Delete
These files can be safely removed:
idd-task-execution-master.mdidd-test-master.mdidd-code-guru.mdidd-e2e-test-queen.md
The validation/sync agents remain useful:
intent-validate.md- Keep (validates Intent structure)intent-sync.md- Keep (syncs implementation back to Intent)intent-audit.md- Keep (project-level health check)
Intent Audit Agent
项目级 Intent 健康检查
触发场景
- 定期检查(每周/每月)
- 新成员 onboard 时了解项目状态
- 大版本发布前
输入
{
"projectRoot": "/path/to/project",
"outputFormat": "markdown" | "json"
}
范围
- Scan all
INTENT.mdfiles underintent/and module-levelintent/directories - Skip
intent/_archive/— archived intents are excluded from all checks - Skip
intent/_data/— generated data files, not intents - Read frontmatter
statusfield when present; default toactiveif omitted
检查维度
1. 覆盖率
模块 Intent 覆盖率:
src/
├── core/
│ └── intent/INTENT.md ✅
├── platforms/
│ ├── web/
│ │ └── intent/ ❌ 缺失
│ ├── cli/
│ │ └── intent/INTENT.md ✅
│ └── desktop/
│ └── intent/ ❌ 缺失
└── chambers/
├── terminal/
│ └── intent/INTENT.md ✅
├── portal/
│ └── intent/INTENT.md ✅
└── taskboard/
└── intent/ ❌ 缺失
覆盖率: 4/7 (57%)
2. 新鲜度
Intent 更新状态:
| 模块 | 最后更新 | 代码最后修改 | 状态 |
|------|---------|-------------|------|
| core | 2026-01-19 | 2026-01-19 | ✅ 同步 |
| terminal | 2026-01-15 | 2026-01-18 | ⚠️ 可能过时 |
| cli | 2026-01-10 | 2026-01-19 | ❌ 严重过时 |
3. 审批状态
Section 审批统计:
项目总计:
├── 🔒 LOCKED: 12 sections
├── ✓ REVIEWED: 28 sections
└── 📝 DRAFT: 45 sections
审批率: 47% (40/85)
需要关注:
- core/intent/INTENT.md 有 8 个 draft sections
- cli/intent/INTENT.md 全部未审批
4. 依赖一致性
检查 intent/architecture/DEPENDENCIES.md 与实际 import 的一致性:
依赖规则检查:
声明的依赖:
API → Chamber ✓
API → Deploy ✓
Deploy → Chamber ✓
实际 import:
API → Chamber ✅ 一致
API → Deploy ✅ 一致
API → Router ❌ 未声明!
Deploy → Chamber ✅ 一致
5. 边界违规
扫描代码,检查 intent/architecture/BOUNDARIES.md 中的规则:
边界规则检查:
规则 1: "上层不直接拼接 appsDir 路径"
├── routes/apps.js:45 ❌ join(appsDir, name)
├── routes/apps.js:78 ❌ join(appsDir, name, 'branches')
└── routes/deploy.js:23 ✅ 使用 chamber.getPath()
规则 2: "deploy 不直接 import router"
└── 全部通过 ✅
违规总计: 2 处
6. Size Budget
Per-intent line count vs tiered thresholds (from intent-standard.md Anti-Accretion Rules):
Size Budget 检查:
| Intent | Lines | Status |
|--------|-------|--------|
| kernel/proc | 413 | ⚠️ Warning (300–500) |
| kernel/afs-scoping | 187 | ✅ Healthy (≤300) |
| ash | 612 | ❌ Blocked (>500) — must run /intent-critique |
Budget Summary: 30 healthy, 8 warning, 4 blocked
Thresholds: ≤ 300 healthy, 300–500 warning, > 500 blocked.
7. Convergence Overdue
Detects intents with ≥ 3 commits since last convergence check (critique/sync):
Convergence 检查:
| Intent | Commits Since | Last Convergence | Status |
|--------|---------------|------------------|--------|
| kernel/proc | 5 | 2026-02-03 | ❌ Overdue (≥3) |
| ash | 1 | 2026-02-05 | ✅ OK |
| surfaces | 4 | null | ❌ Never converged |
Convergence Overdue: 6 intents
Detection method: Count git commits touching INTENT.md since the most recent records/critique-*.md or records/sync-*.md entry in records/INDEX.md.
8. Analysis Ratio
Classifies sections as constraint (testable rule) vs analysis (background/exploration). High analysis ratio suggests the intent needs convergence:
Analysis Ratio 检查:
| Intent | Total Sections | Analysis | Ratio | Status |
|--------|---------------|----------|-------|--------|
| kernel/proc | 12 | 2 | 17% | ✅ OK |
| ash | 15 | 8 | 53% | ⚠️ High analysis content |
Heuristic: Sections with words like "Background", "Context", "Exploration", "Notes", "Discussion", "Options", "Alternatives" are classified as analysis. Sections with "API", "Constraints", "Rules", "Structure", "Invariants", "Parameters" are classified as constraint.
9. Orphan Detection
Intents with no Assumes: edges in or out — not depended on and not depending on anything:
Orphan 检查:
Orphan intents (no dependency edges):
- surfaces
- legacy/migration
- experimental/playground
Orphans: 3 intents (of 42 total)
Note: Root-level project intent and leaf intents may legitimately have no edges. Flag for review, not necessarily an error.
10. Stale References
Assumes: tags pointing to deleted or moved intents:
Stale Reference 检查:
| From | References | Status |
|------|-----------|--------|
| ash | kernel/echo | ❌ Target deleted |
| api/gateway | auth/legacy | ❌ Target moved to auth/v2 |
Stale References: 2
Detection: For each Assumes: target, verify the corresponding intent/<id>/INTENT.md exists.
输出
Markdown 报告
# Intent Audit Report
> 项目: ainecore
> 日期: 2026-01-19
> 执行者: intent-audit agent
## 总览
| 指标 | 值 | 状态 |
|------|-----|------|
| 模块覆盖率 | 57% | ⚠️ |
| 审批率 | 47% | ⚠️ |
| 依赖一致性 | 92% | ✅ |
| 边界合规 | 85% | ⚠️ |
| Size Budget | 30/42 healthy | ⚠️ |
| Convergence | 6 overdue | ❌ |
| Orphans | 15 intents | ⚠️ |
| Stale Refs | 4 broken | ❌ |
## 健康分数: 72/100
## 优先行动
### P0 - 立即处理
1. 修复 2 处边界违规 (routes/apps.js)
2. 补充 cli 模块的 Intent 审批
### P1 - 本周处理
1. 为 web, desktop, taskboard 添加 Intent
2. 更新 cli Intent(严重过时)
### P2 - 计划中
1. 提高审批率到 70%
2. 添加 DEPENDENCIES.md
## 详细报告
[展开各维度详情...]
JSON 报告 (Structured Output)
When outputFormat: "json", generate intent/_data/intent-health.json and intent/_data/intent-graph.json following the schemas defined in intent-data-format.md.
intent-health.json — per-intent metrics including anti-accretion checks:
{
"generated": "2026-02-06T10:00:00Z",
"version": "1.0",
"intents": {
"kernel/proc": {
"path": "intent/kernel/proc/INTENT.md",
"lines": 413,
"budget_status": "warning",
"anchor": "Process lifecycle management for AOS kernel",
"assumes": ["kernel/afs-scoping"],
"commits_since_convergence": 5,
"last_modified": "2026-02-05",
"last_convergence": "2026-02-03",
"convergence_due": true,
"sections": 12,
"analysis_sections": 2,
"approval": { "locked": 3, "reviewed": 5, "draft": 4 }
}
},
"summary": {
"total": 42,
"healthy": 30,
"warning": 8,
"blocked": 4,
"orphans": 15,
"stale_refs": 4,
"convergence_overdue": 6
}
}
intent-graph.json — dependency graph:
{
"generated": "2026-02-06T10:00:00Z",
"version": "1.0",
"nodes": [
{ "id": "kernel/proc", "anchor": "...", "lines": 413, "status": "warning" }
],
"edges": [
{ "from": "kernel/proc", "to": "kernel/afs-scoping", "type": "assumes" }
],
"orphans": ["surfaces"],
"stale_refs": [
{ "from": "ash", "to": "kernel/echo", "reason": "target deleted" }
]
}
Output location: intent/_data/ directory (created if not exists).
Legacy JSON 报告
For backward compatibility, the inline JSON report is still supported:
{
"project": "ainecore",
"date": "2026-01-19",
"score": 72,
"coverage": {
"total": 7,
"covered": 4,
"percentage": 57
},
"approval": {
"locked": 12,
"reviewed": 28,
"draft": 45,
"percentage": 47
},
"violations": [
{
"file": "routes/apps.js",
"line": 45,
"rule": "no-direct-path",
"severity": "error"
}
],
"recommendations": [...]
}
集成
CI/CD 集成
# .github/workflows/intent-audit.yml
name: Intent Audit
on:
schedule:
- cron: '0 9 * * 1' # 每周一早上
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run Intent Audit
run: claude --agent intent-audit --output audit-report.md
- name: Upload Report
uses: actions/upload-artifact@v4
with:
name: intent-audit-report
path: audit-report.md
阈值告警
{
"thresholds": {
"coverage": 70,
"approval": 60,
"violations": 0
},
"failOnThreshold": true
}
Intent Sync Agent
检查代码实现与 Intent 的一致性
触发场景
- 开发完成后,验证实现是否符合 Intent
- PR Review 时,检查变更是否在 Intent 范围内
- 定期同步检查
输入
{
"intentPath": "src/core/intent/INTENT.md",
"codePath": "src/core/src/",
// 或
"module": "core" // 自动推断路径
}
检查维度
1. API 一致性
对比 Intent 中的 API 定义与实际代码:
| 检查项 | 说明 |
|---|---|
| 函数存在性 | Intent 定义的函数是否都已实现 |
| 签名匹配 | 参数名、类型是否一致 |
| 返回值 | 返回类型是否符合 |
| 新增 API | 代码中有但 Intent 未记录的 |
2. 数据结构一致性
对比 Intent 中的数据结构与实际代码:
Intent 定义:
Chamber {
name: string
branches: Branch[]
}
实际代码:
Chamber {
name: string
branches: Branch[]
createdAt: Date // ← 新增,Intent 未记录
}
3. 行为一致性
检查 Intent 中描述的行为是否在代码中体现:
Intent: "删除 chamber 时移动到 .trash/"
Code: fs.rmSync(chamberPath) // ← 不一致!直接删除
4. 边界规则
检查 BOUNDARIES.md 中的规则是否被遵守:
规则: "deploy.js 不允许直接 import router"
代码: import { matchRoute } from '../router' // ← 违规!
输出
# Intent Sync Report
## Module: core
### API 一致性
| API | Intent | Code | 状态 |
|-----|--------|------|------|
| `createChamber()` | ✓ | ✓ | ✅ 一致 |
| `deleteChamber()` | ✓ | ✓ | ⚠️ 签名差异 |
| `getChamberStats()` | ✗ | ✓ | 📝 新增未记录 |
### 签名差异详情
```diff
# deleteChamber
- Intent: deleteChamber(app, name)
+ Code: deleteChamber(app, name, options)
数据结构差异
# Chamber
{
name: string
branches: Branch[]
+ createdAt: Date // 新增
+ metadata: object // 新增
}
边界规则检查
| 规则 | 状态 |
|---|---|
| deploy 不直接访问 router | ✅ 通过 |
| API 层通过 chamber.js | ⚠️ 1 处违规 |
行动建议
-
更新 Intent (推荐)
- 添加
getChamberStats()API 文档 - 补充
createdAt,metadata字段
- 添加
-
修改代码
deleteChamber移除 options 参数(如果不需要)
-
修复违规
routes/apps.js:45直接拼接路径,应使用 chamber.js API
## 同步模式
### 模式 1: Intent → Code (验证)
检查代码是否实现了 Intent 的要求。
### 模式 2: Code → Intent (发现)
发现代码中有但 Intent 未记录的内容。
### 模式 3: 双向同步
同时执行两个方向,生成完整差异报告。
## 与 Git 集成
```bash
# 检查本次 PR 的变更是否与 Intent 一致
intent-sync --git-diff origin/main
只检查变更涉及的模块,忽略未改动部分。
Intent Validate Agent
检查 Intent 文件是否符合 IDD 规范
触发场景
- Intent 文件被创建或修改后
/intent-review前自动执行- 手动调用进行全量检查
输入
{
"path": "src/core/intent/INTENT.md", // 具体文件
// 或
"scope": "project" // 项目级扫描
}
检查项
1. 结构完整性
| 检查项 | 必须 | 说明 |
|---|---|---|
| Anchor | ✓ | 标题后紧跟 > Anchor: 或 > 一句话锚点声明 |
| 状态头 | ✓ | 包含 "状态" 和 "最后更新" |
| 职责 | ✓ | 明确 "做什么" |
| 非目标 | ✓ | 明确 "不做什么" |
| 数据结构 | - | 如有数据,需定义 |
| API | - | 如有接口,需定义 |
1.5 Size Budget
| 行数 | 状态 | 说明 |
|---|---|---|
| ≤ 300 | ✅ 健康 | 无需操作 |
| 300–500 | ⚠️ 警告 | 提示拆分或精简 |
| > 500 | ❌ 阻断 | 必须先跑 /intent-critique 才能继续加内容 |
超出 budget 时输出 warning:
⚠️ Size Budget Warning (or ❌ Size Budget Exceeded)
- File: src/core/intent/INTENT.md
- Current: 437 lines
- Status: WARNING (300-500)
- Action: Consider running /intent-critique to split or trim
500 行时输出 error:
❌ Size Budget Exceeded
- File: src/core/intent/INTENT.md
- Current: 612 lines
- Status: BLOCKED (>500)
- Action: Run /intent-critique before adding any new content
2. 层级正确性
| 内容 | 应在项目级 | 应在模块级 |
|---|---|---|
| 愿景目标 | ✓ | ✗ |
| 模块索引 | ✓ | ✗ |
| 依赖关系 | ✓ | ✗ |
| 模块职责 | ✗ | ✓ |
| API 签名 | ✗ | ✓ |
3. 格式规范
- 使用 ASCII 图而非纯文字描述结构
- API 定义包含:参数、返回值、约束
- 示例包含:输入 → 输出
4. Section 标记
::: locked/reviewed/draft语法正确- 属性格式正确
{key=value} - 日期格式:YYYY-MM-DD
输出
# Intent Validation Report
## 文件: src/core/intent/INTENT.md
### ✅ 通过 (5)
- [x] 状态头存在
- [x] 职责定义清晰
- [x] 非目标明确
- [x] API 定义完整
- [x] 示例齐全
### ⚠️ 警告 (2)
- [ ] 缺少 ASCII 结构图
- [ ] 部分 API 缺少约束说明
### ❌ 错误 (1)
- [ ] 项目级内容出现在模块级 Intent (愿景目标应在 intent/INTENT.md)
## 合规分数: 78/100
自动修复
对于可自动修复的问题:
可自动修复:
- 添加缺失的状态头模板
- 格式化 Section 标记语法
- 添加缺失的日期属性
需要人工处理:
- 补充非目标
- 添加 API 约束
- 调整层级位置
Sponsors
Details
- Marketplace
- ArcBlock/idd
- Category
- Community