Harness Engineering，再到 Trellis 落地实战#

1
Superpowers 核心理念：
2
┌─────────────────────────────────────────────┐
3
│                                             │
4
│  brainstorming  →  需求分析和方案发散         │
5
│  plan           →  技术方案设计               │
6
│  TDD            →  测试驱动开发               │
7
│  review         →  代码审查                   │
8
│                                             │
9
│  每个 Skill = 一个文件夹                      │
10
│  ├── skill.md   （指令，按需加载）             │
11
│  ├── scripts/   （脚本，执行时调用）           │
12
│  └── templates/ （模板，参考使用）             │
13
│                                             │
14
└─────────────────────────────────────────────┘

1
OpenSpec 工作流：
2
  proposal  →  spec  →  design  →  tasks
3
  (提案)       (规范)    (设计)     (任务拆解)

1
oh-my-claudecode 架构：
2
  ┌──────────────────────────────────────┐
3
  │          Team Lead (主会话)           │
4
  │    /autopilot  /team  magic keywords │
5
  └──────────────┬───────────────────────┘
6
                 │
7
     ┌───────────┼───────────┬───────────┐
8
     ▼           ▼           ▼           ▼
9
  Agent 1    Agent 2    Agent 3    Agent 4
10
  (架构)      (后端)      (前端)      (测试)

1
┌────────────────────────────────────────────────────────────┐
2
│                      Trellis 三层架构                        │
3
├────────────────────────────────────────────────────────────┤
4
│                                                            │
5
│  ┌──────────────────────────────────────────────────────┐  │
6
│  │               Layer 1: Spec（规范层）                  │  │
7
│  │  .trellis/spec/                                       │  │
8
│  │  ├── shared/          # 跨层共享规范                    │  │
9
│  │  │   ├── index.md     # 编码规范总览                    │  │
10
│  │  │   ├── cross-layer-thinking-guide.md                 │  │
11
│  │  │   └── code-reuse-thinking-guide.md                  │  │
12
│  │  ├── backend/         # 后端规范                        │  │
13
│  │  │   ├── index.md                                      │  │
14
│  │  │   ├── database-guidelines.md                        │  │
15
│  │  │   ├── error-handling.md                             │  │
16
│  │  │   ├── logging-guidelines.md                         │  │
17
│  │  │   ├── api-module.md                                 │  │
18
│  │  │   └── quality-guidelines.md                         │  │
19
│  │  └── frontend/        # 前端规范（如有）                 │  │
20
│  │ 作用：定义"代码应该写成什么样"                             │  │
21
│  └──────────────────────────────────────────────────────┘  │
22
│                                                            │
23
│  ┌──────────────────────────────────────────────────────┐  │
24
│  │               Layer 2: Task（任务层）                   │  │
25
│  │  .trellis/tasks/                                      │  │
26
│  │  ├── task.json       # 任务元数据（状态、负责人、分支）   │  │
27
│  │  ├── prd.md          # 需求文档                         │  │
28
│  │  ├── implement.jsonl # 实现阶段的上下文文件列表           │  │
29
│  │  ├── check.jsonl     # 检查阶段的上下文文件列表           │  │
30
│  │  └── debug.jsonl     # 调试阶段的上下文文件列表           │  │
31
│  │ 作用：管理"当前在做什么、做到哪了、还需要什么上下文"        │  │
32
│  └──────────────────────────────────────────────────────┘  │
33
│                                                            │
34
│  ┌──────────────────────────────────────────────────────┐  │
35
│  │            Layer 3: Workspace（工作区层）               │  │
36
│  │  .trellis/workspace/                                  │  │
37
│  │  └── {developer}/                                     │  │
38
│  │      ├── journal-1.md   # 工作日志（记录每次会话）       │  │
39
│  │      ├── journal-2.md                                  │  │
40
│  │      └── ...                                           │  │
41
│  │ 作用：记录"每次会话做了什么、学到了什么"                   │  │
42
│  └──────────────────────────────────────────────────────┘  │
43
│                                                            │
44
└────────────────────────────────────────────────────────────┘

1
{
2
  "id": "02-27-user-login",
3
  "name": "user-login",
4
  "title": "用户登录功能",
5
  "description": "实现基于 JWT 的用户登录和 token 刷新",
6
  "status": "in_progress",
7
  "dev_type": "backend",
8
  "scope": "auth",
9
  "priority": "P1",
10
  "creator": "wcxian",
11
  "assignee": "wcxian",
12
  "branch": "feature/user-login",
13
  "base_branch": "main",
14
  "subtasks": [],
15
  "relatedFiles": [],
16
  "next_action": [
17
    { "phase": 1, "action": "implement" },
18
    { "phase": 2, "action": "check" },
19
    { "phase": 3, "action": "finish" },
20
    { "phase": 4, "action": "create-pr" }
21
  ]
22
}

1
                    ┌─────────────┐
2
                    │   Created   │  ← task.py create
3
                    │   (已创建)   │    after_create hook
4
                    └──────┬──────┘
5
                           │
6
                           ▼
7
                 ┌─────────────────┐
8
                 │  In Progress    │  ← task.py start
9
                 │   (进行中)       │    after_start hook
10
                 │                 │    自动创建 Git Worktree
11
                 │  • Phase 1      │    自动创建 Work Journal
12
                 │    implement    │    JSONL 上下文注入
13
                 │  • Phase 2      │
14
                 │    check        │
15
                 └────────┬────────┘
16
                          │
17
                          ▼
18
                 ┌─────────────────┐
19
                 │   Finished      │  ← /finish-work
20
                 │   (已完成)       │    after_finish hook
21
                 │                 │    AI Code Review
22
                 │                 │    Spec 合规检查
23
                 └────────┬────────┘
24
                          │
25
                          ▼
26
                 ┌─────────────────┐
27
                 │   Archived      │  ← /record-session
28
                 │   (已归档)       │    after_archive hook
29
                 │                 │    知识沉淀 + 会话存档
30
                 └─────────────────┘

1
{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
2
{"file": ".trellis/spec/shared/index.md", "reason": "Shared coding standards"}
3
{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
4
{"file": ".trellis/spec/backend/api-module.md", "reason": "API module conventions"}
5
{"file": ".trellis/spec/backend/quality.md", "reason": "Code quality requirements"}

1
{"file": ".claude/commands/trellis/finish-work.md", "reason": "Finish work checklist"}
2
{"file": ".trellis/spec/shared/index.md", "reason": "Shared coding standards"}
3
{"file": ".claude/commands/trellis/check-backend.md", "reason": "Backend check spec"}

1
hot-news/
2
├── .trellis/                    # 新增
3
│   ├── spec/
4
│   │   ├── shared/
5
│   │   │   └── index.md
6
│   │   ├── backend/
7
│   │   │   └── index.md
8
│   │   └── guides/
9
│   │       └── index.md
10
│   ├── tasks/
11
│   ├── workspace/
12
│   │   └── wcxian/
13
│   │       └── journal-1.md
14
│   └── workflow.md
15
├── .claude/                     # 新增（如果使用 Claude Code）
16
│   └── commands/trellis/
17
├── src/                         # 原有代码不变
18
└── pom.xml

1
/trellis:continue

1
## Controller 层规范
2
- 使用 @RestController + @RequestMapping 注解
3
- 统一返回 Result<T> 包装类
4
- API 路径使用 kebab-case：/api/v1/hot-news
5
- 参数校验使用 @Valid + BindingResult

1
"帮我查一下为什么定时任务会重复采集数据"
2
→ AI 分析代码，发现缺少分布式锁
3
→ 加一把 Redis 分布式锁
4
→ 提交，完事

1
根因类别：并发控制缺失
2
问题表现：定时任务在分布式环境下重复执行
3
为什么之前的修复失败了：
4
  - 第一次修复：增加了唯一索引 → 不够，因为采集时间不同所以索引不冲突
5
  - 第二次修复：增加了时间窗口判断 → 不够，因为多实例同时执行时窗口判断也同时通过
6
根本原因：没有在分布式层面做互斥控制
7

8
预防机制：
9
  1. 在 database-guidelines.md 中增加"定时任务必须使用分布式锁"
10
  2. 在 quality-guidelines.md 中增加"定时任务检查清单"
11
  3. 提供一个分布式锁的参考实现模板

1
## 新增：定时任务规范（database-guidelines.md）
2

3
### 分布式锁要求
4
所有定时任务必须使用分布式锁（Redis/Redisson），防止多实例重复执行：
5

6
@Scheduled(cron = "0 */30 * * * ?")
7
public void crawlHotList() {
8
    RLock lock = redissonClient.getLock("lock:zhihu-crawl");
9
    if (lock.tryLock(0, 25, TimeUnit.MINUTES)) {
10
        try {
11
            // 采集逻辑
12
        } finally {
13
            lock.unlock();
14
        }
15
    }
16
}