日常使用

create → init-context → add-context → start → implement/check → finish → archive
  │           │              │           │          │               │         │
  │           │              │           │          │               │         │
  ▼           ▼              ▼           ▼          ▼               ▼         ▼
创建        初始化 JSONL    追加上下文    设为当前   开发 /          清除      归档到
目录        配置文件        条目          任务指针   检查循环        当前      archive/
task.json                                                           任务

# 创建任务
TASK_DIR=$(./.trellis/scripts/task.py create "新增用户登录" \
  --slug user-login \          # 目录名后缀（可选，不写自动生成）
  --assignee alice \           # 负责人（可选）
  --priority P1 \              # 优先级：P0/P1/P2/P3（可选，默认 P2）
  --description "实现 JWT 登录")  # 描述（可选）

# 创建的目录：.trellis/tasks/02-27-user-login/
# 创建的文件：task.json

# 初始化 JSONL 配置（生成 implement.jsonl + check.jsonl）
./.trellis/scripts/task.py init-context "$TASK_DIR" backend
# dev_type：backend | frontend | fullstack | test | docs
# 可选：--package PACKAGE   （monorepo 必填，选 spec/<pkg>/ 根）

# 追加额外的上下文条目
./.trellis/scripts/task.py add-context "$TASK_DIR" implement \
  "src/services/auth.ts" "现有 auth 模式"
# file 参数：implement | check（简写，自动补 .jsonl）
# path 参数：文件 or 目录路径，add-context 自动识别目录并设 type="directory"

# 校验 implement.jsonl + check.jsonl 里引用的文件都存在
./.trellis/scripts/task.py validate "$TASK_DIR"

# 查看所有 JSONL 条目
./.trellis/scripts/task.py list-context "$TASK_DIR"

# 设为当前任务（sub-agent hook 读 .current-task 做 JSONL 注入）
./.trellis/scripts/task.py start "$TASK_DIR"

# 清除当前任务（无参数，自动读 .current-task）
./.trellis/scripts/task.py finish

# 设置 Git 分支名
./.trellis/scripts/task.py set-branch "$TASK_DIR" "feature/user-login"

# 设置 PR 目标分支
./.trellis/scripts/task.py set-base-branch "$TASK_DIR" "main"

# 设置 scope（用在 commit message：feat(scope): ...）
./.trellis/scripts/task.py set-scope "$TASK_DIR" "auth"

# 方式 A：在父任务下直接建子任务
./.trellis/scripts/task.py create "JWT middleware" \
  --slug jwt-middleware \
  --parent 02-27-user-login

# 方式 B：把两个已有任务链起来
./.trellis/scripts/task.py add-subtask \
  02-27-user-login \                # 父任务目录
  02-28-jwt-middleware              # 子任务目录

# 解除关联（不会删除任何任务）
./.trellis/scripts/task.py remove-subtask \
  02-27-user-login 02-28-jwt-middleware

# 列出活跃任务
./.trellis/scripts/task.py list
./.trellis/scripts/task.py list --mine            # 只看自己的
./.trellis/scripts/task.py list --status review   # 按状态过滤

# 归档完成的任务
./.trellis/scripts/task.py archive user-login
# 移动到 archive/2026-02/

# 列出归档任务
./.trellis/scripts/task.py list-archive
./.trellis/scripts/task.py list-archive 2026-02  # 按月过滤

{
  "id": "02-27-user-login",
  "name": "user-login",
  "title": "新增用户登录",
  "description": "实现 JWT 登录流程",
  "status": "planning",
  "dev_type": null,
  "scope": null,
  "package": null,
  "priority": "P1",
  "creator": "alice",
  "assignee": "alice",
  "createdAt": "2026-02-27",
  "completedAt": null,
  "branch": null,
  "base_branch": "main",
  "worktree_path": null,
  "commit": null,
  "pr_url": null,
  "subtasks": [],
  "children": [],
  "parent": null,
  "relatedFiles": [],
  "notes": "",
  "meta": {}
}

task.py create     →  status: "planning"
task.py start      →  （只写 .trellis/.current-task，不改 status）
（手动或未来脚本）  →  status: "in_progress"
task.py archive    →  status: "completed" + 移到 archive/

# implement.jsonl
{"file": ".trellis/workflow.md", "reason": "项目工作流和约定"}
{"file": ".trellis/spec/backend/index.md", "reason": "后端开发指南"}

# check.jsonl（路径按当前平台解析到对应 command / skill 位置）
{"file": ".claude/commands/trellis/finish-work.md", "reason": "收尾清单"}
{"file": ".claude/commands/trellis/check.md", "reason": "质量检查规范"}

# 把现有代码作为参考（文件）
./.trellis/scripts/task.py add-context "$TASK_DIR" implement \
  "src/services/user.ts" "现有 user service 模式"

# 整个目录（自动读所有 .md）
./.trellis/scripts/task.py add-context "$TASK_DIR" implement \
  "src/services/" "现有 service 模式"

# 自定义 check 上下文
./.trellis/scripts/task.py add-context "$TASK_DIR" check \
  ".trellis/spec/guides/cross-layer-thinking-guide.md" "跨层验证"

hooks:
  after_create:
    - 'python3 .trellis/scripts/hooks/linear_sync.py create'
  after_start:
    - 'python3 .trellis/scripts/hooks/linear_sync.py start'
  after_finish:
    - "echo 'Task finished'"
  after_archive:
    - 'python3 .trellis/scripts/hooks/linear_sync.py archive'

{
  "linear": {
    "team": "ENG",
    "project": "我的项目",
    "assignees": {
      "alice": "linear-user-id-for-alice"
    }
  }
}

.trellis/spec/
├── frontend/                    # 前端规范（占位）
│   ├── index.md                 #   索引：列出所有规范及状态
│   ├── component-guidelines.md  #   组件规范
│   ├── hook-guidelines.md       #   Hook 规范
│   ├── state-management.md      #   状态管理
│   ├── type-safety.md           #   类型安全
│   ├── quality-guidelines.md    #   质量指南
│   └── directory-structure.md   #   目录结构
│
├── backend/                     # 后端规范（占位）
│   ├── index.md
│   ├── database-guidelines.md
│   ├── error-handling.md
│   ├── logging-guidelines.md
│   ├── quality-guidelines.md
│   └── directory-structure.md
│
└── guides/                      # 思维指南
    ├── index.md
    ├── cross-layer-thinking-guide.md
    └── code-reuse-thinking-guide.md

.trellis/spec/                                # Trellis 自己的 spec 树
├── cli/                                      # Package: CLI
│   ├── backend/
│   │   └── index.md                          #   ← 通过 index.md 注册为一层
│   └── unit-test/
│       └── index.md                          #   ← 又一层
│
├── docs-site/                                # Package: 文档站
│   └── docs/
│       └── index.md                          #   ← 单层 package
│
└── guides/                                   # 跨 package 的思维指南
    ├── index.md
    ├── cross-layer-thinking-guide.md
    ├── cross-platform-thinking-guide.md
    └── code-reuse-thinking-guide.md

# 看看现有代码是怎么组织的
ls src/components/     # 组件结构
ls src/services/       # 服务结构

# Component Guidelines

## File Structure

- One component per file
- Use PascalCase for filenames: `UserProfile.tsx`
- Co-locate styles: `UserProfile.module.css`
- Co-locate tests: `UserProfile.test.tsx`

## Patterns

#### Required

- Functional components + hooks (no class components)
- TypeScript with explicit Props interface
- `export default` for page components, named export for shared

#### Forbidden

- No `any` type in Props
- No inline styles (use CSS Modules)
- No direct DOM manipulation

#### Good Example

```tsx
interface UserProfileProps {
  userId: string;
  onUpdate: (user: User) => void;
}

export function UserProfile({ userId, onUpdate }: UserProfileProps) {
  // ...
}
```

#### Bad Example

```tsx
// Don't: no Props interface, using any
export default function UserProfile(props: any) {
  // ...
}
```

| Guideline | File | Status |
|-----------|------|--------|
| Component Guidelines | component-guidelines.md | **Filled** |
| Hook Guidelines | hook-guidelines.md | To fill |

#### Convention：用 ORM batch 方法，别在循环里一条一条写 DB

**What**：对 N 条数据，调一次 ORM 的 batch 方法（`createMany` / `updateMany` / `deleteMany`）。不要把单行 `create` / `update` / `delete` 套进 `for` 或 `Promise.all`。

**Why**：每次 DB 调用都是一次 round-trip。线上接口里一个 200 条的循环就能把 p99 从 50ms 悄悄拖到 8s——这种坑已经在 code review 里抓到过两次（PR #312、#417）。Batch 方法把 N 次 round-trip 压成一次 SQL，DB 可以自己规划写入。

**Example**：
```ts
// ✅ 正确——一次 round-trip
await prisma.user.createMany({ data: users });

// ❌ 错误——N 次 round-trip
for (const user of users) {
  await prisma.user.create({ data: user });
}

// ❌ 还是错——并发的 N 次 round-trip
await Promise.all(users.map(user => prisma.user.create({ data: user })));
```

**Batch 不可用时**：把循环包进单事务（`prisma.$transaction`），至少是一个逻辑单元；加注释说明为什么 batch 用不了。

**Related**：`quality-guidelines.md#performance`、`error-handling.md#transactions`。

#### Database
- Use good query patterns
- Be careful with SQL
- Follow best practices

#### Variable Naming
- All boolean variables must start with `is` or `has`
- All arrays must end with `List`
- All functions must be less than 20 lines
- All files must be less than 200 lines