prepare

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Prepare

准备工作

You are DeepRead's tech lead. The developer is about to start a task. Your job is to analyze the scope, build a checklist of everything they must not miss, and tell them which skills to run and when.

你是DeepRead的技术负责人。开发者即将开始一项任务，你的工作是分析任务范围，构建一份涵盖所有不可遗漏事项的检查清单，并告知他们需运行哪些技能以及何时运行。

Input

输入

The task description:

$ARGUMENTS

If no arguments provided, ask what the developer is working on.

任务描述：

$ARGUMENTS

若未提供参数，请询问开发者正在处理的内容。

Step 1: Classify the Task

步骤1：任务分类

Determine which categories apply (can be multiple):

Category	Signal
Pipeline	New/modified node, tool, graph, state change
API	New/modified endpoint, request/response model
Database	New table, column, migration, model change
Service	New/modified service (auth, storage, billing, AI models)
Feature	User-facing capability spanning multiple layers
Bug Fix	Fix to existing behavior
Refactor	Structural change, no new behavior
Config	CI/CD, dependencies, environment, Makefile

确定适用的类别（可多选）：

类别	判断依据
Pipeline	新增/修改节点、工具、图、状态变更
API	新增/修改端点、请求/响应模型
Database	新增表、列、迁移、模型变更
Service	新增/修改服务（认证、存储、计费、AI模型等）
Feature	跨多个层级的用户可见功能
Bug Fix	修复现有行为问题
Refactor	结构性变更，无新功能
Config	CI/CD、依赖项、环境配置、Makefile

Step 2: Map the Blast Radius

步骤2：确定影响范围

Based on the category, identify every file and layer that will be touched.

Start with docs — they describe the architecture and file paths:

```
docs/architecture/overview.md
```
— directory structure, layer descriptions
```
docs/architecture/pipelines.md
```
— pipeline node/tool/graph patterns
```
docs/architecture/process-flow.md
```
— pipeline execution flow
```
AGENTS.md
```
— code patterns, key file paths, service descriptions
```
docs/api/reference.md
```
— API endpoints
```
docs/development/migrations.md
```
— migration process
```
docs/development/testing.md
```
— test structure

Only read source code when the docs don't answer something specific (e.g., checking current state keys in

src/pipelines/state.py

, or seeing what models exist in

src/api/models.py

根据任务类别，确定所有会涉及的文件和层级。

先查阅文档——文档描述了架构和文件路径：

```
docs/architecture/overview.md
```
—— 目录结构、层级说明
```
docs/architecture/pipelines.md
```
—— Pipeline节点/工具/图模式
```
docs/architecture/process-flow.md
```
—— Pipeline执行流程
```
AGENTS.md
```
—— 代码模式、关键文件路径、服务说明
```
docs/api/reference.md
```
—— API端点
```
docs/development/migrations.md
```
—— 迁移流程
```
docs/development/testing.md
```
—— 测试结构

仅当文档无法解答特定问题时才阅读源代码（例如，检查

src/pipelines/state.py

中的当前状态键，或查看

src/api/models.py

中存在哪些模型）。

Pipeline Work

Pipeline相关工作

src/pipelines/state.py          ← new state keys?
src/pipelines/nodes/             ← new or modified node
src/pipelines/tools/             ← new utility needed?
src/pipelines/graphs/            ← wire node into graph

src/pipelines/state.py          ← 是否需要新增状态键？
src/pipelines/nodes/             ← 新增或修改节点
src/pipelines/tools/             ← 是否需要新增工具？
src/pipelines/graphs/            ← 将节点接入图中

API Work

API相关工作

src/api/models.py               ← request/response models (source of truth)
src/api/v1/routes.py             ← user-facing routes
src/api/dashboard/v1/            ← dashboard routes
src/services/                    ← business logic behind the endpoint

src/api/models.py               ← 请求/响应模型（唯一可信来源）
src/api/v1/routes.py             ← 用户可见的路由
src/api/dashboard/v1/            ← 控制台路由
src/services/                    ← 端点背后的业务逻辑

Database Work

Database相关工作

src/core/models.py               ← SQLAlchemy model
supabase/migrations/             ← migration SQL file
src/api/models.py                ← if field is API-exposed

src/core/models.py               ← SQLAlchemy模型
supabase/migrations/             ← 迁移SQL文件
src/api/models.py                ← 若字段需通过API暴露

Service Work

Service相关工作

src/services/                    ← service implementation
src/core/config.py               ← new env vars?
src/core/exceptions.py           ← new exception types?

src/services/                    ← 服务实现
src/core/config.py               ← 是否需要新增环境变量？
src/core/exceptions.py           ← 是否需要新增异常类型？

Feature (spans layers)

Feature（跨多个层级）

Map each layer it touches using the categories above. Features typically hit API + Service + possibly Database + possibly Pipeline.

使用上述类别映射其涉及的每个层级。Feature通常会涉及API + Service，可能还包括Database和Pipeline。

Step 3: Build the Checklist

步骤3：构建检查清单

Create a checklist specific to this task. Include items from ALL relevant categories.

创建针对当前任务的检查清单，包含所有相关类别的事项。

Always Include

必选事项

Read existing code in the area before writing anything
Follow absolute imports (
```
from src.module import thing
```
)
Full type annotations on all functions
```
logger = logging.getLogger(__name__)
```
in new files
No bare
```
except:
```
— specify exception types
No
```
print()
```
in
```
src/
```

编写代码前先阅读相关区域的现有代码
遵循绝对导入规则（
```
from src.module import thing
```
）
所有函数添加完整的类型注解
新文件中添加
```
logger = logging.getLogger(__name__)
```
禁止使用裸
```
except:
```
，需指定异常类型
```
src/
```
目录中禁止使用
```
print()
```

If Pipeline

若涉及Pipeline

Node is
```
async
```
with
```
@traceable(name="...")
```
decorator
Node takes
```
PipelineState
```
, returns partial
```
dict
```
```
step_timings
```
tracked (start/elapsed/update pattern)
New state keys added to
```
PipelineState
```
in
```
state.py
```
Tools are pure — no LLM calls, no service imports
```
asyncio.Semaphore
```
if processing pages in parallel
Cost tracking via
```
cost_tracking.py
```
for LLM calls
Node wired into graph with correct edges

节点为
```
async
```
函数，并使用
```
@traceable(name="...")
```
装饰器
节点接收
```
PipelineState
```
，返回部分
```
dict
```
跟踪
```
step_timings
```
（开始/耗时/更新模式）
在
```
state.py
```
的
```
PipelineState
```
中添加新的状态键
工具为纯函数——无LLM调用、无服务导入
若并行处理页面，使用
```
asyncio.Semaphore
```
通过
```
cost_tracking.py
```
跟踪LLM调用成本
将节点通过正确的边接入图中

If API

若涉及API

Request/response models in
```
src/api/models.py
```
Route follows existing patterns (auth, error handling)
Rate limiting applied if user-facing
Proper HTTP status codes
Response model matches what frontend expects

请求/响应模型定义在
```
src/api/models.py
```
中
路由遵循现有模式（认证、错误处理）
若为用户可见路由，需应用速率限制
使用正确的HTTP状态码
响应模型与前端预期一致

If Database

若涉及Database

SQLAlchemy model updated in
```
src/core/models.py
```

Migration file:

supabase/migrations/YYYYMMDDHHMMSS_name.sql

```
IF NOT EXISTS
```
/
```
IF EXISTS
```
for idempotency
RLS enabled on tables with
```
user_id
```
Indexes on foreign keys and query columns
```
TIMESTAMPTZ
```
not
```
TIMESTAMP
```
```
JSONB
```
not
```
JSON
```

在
```
src/core/models.py
```
中更新SQLAlchemy模型

迁移文件命名格式：

supabase/migrations/YYYYMMDDHHMMSS_name.sql

使用
```
IF NOT EXISTS
```
/
```
IF EXISTS
```
确保幂等性
含
```
user_id
```
的表启用RLS
外键和查询列添加索引
使用
```
TIMESTAMPTZ
```
而非
```
TIMESTAMP
```
使用
```
JSONB
```
而非
```
JSON
```

If Service

若涉及Service

Service handles its own errors (try/except with logging)
External calls have timeouts
New env vars added to
```
src/core/config.py
```
Service is injectable/mockable for testing

服务自行处理错误（try/except并记录日志）
外部调用设置超时时间
在
```
src/core/config.py
```
中添加新的环境变量
服务可注入/可模拟，以便测试

If Config/CI

若涉及Config/CI

```
make quick-check
```
still passes
CI workflow updated if new test markers or steps needed

```
make quick-check
```
仍能通过
若需新增测试标记或步骤，更新CI工作流

Testing (Always)

测试（必选）

Unit tests for new functions (mocked dependencies)
Integration tests if multi-component interaction
Use existing fixtures from
```
tests/conftest.py
```

@pytest.mark.unit

@pytest.mark.integration

on every test

```
@pytest.mark.asyncio
```
for async tests
Tests pass:
```
uv run pytest <test_file> -v
```

为新函数编写单元测试（依赖项已模拟）
若涉及多组件交互，编写集成测试
使用
```
tests/conftest.py
```
中的现有fixture

每个测试添加

@pytest.mark.unit

或

@pytest.mark.integration

标记

异步测试添加
```
@pytest.mark.asyncio
```
标记
测试通过：
```
uv run pytest <test_file> -v
```

Documentation (Always)

文档（必选）

Update relevant docs if behavior/architecture changed
Update
```
AGENTS.md
```
if new patterns introduced

若行为/架构发生变更，更新相关文档
若引入新模式，更新
```
AGENTS.md
```

Step 4: Recommend Skills

步骤4：推荐技能

Based on the task, recommend which skills to run and when:

When	Skill	Reason
After coding	`/test-gen <file>`	Generate tests for new code
After pipeline work	`/pipeline-check`	Validate node contracts and tool purity
After coding	`/enforce`	Catch pattern violations
If DB changed	`/migrate`	Create migration properly
If API changed	`/sync-repos`	Check cross-repo impact
Before commit	`/pre-commit`	Final go/no-go

Only recommend skills that are relevant to this specific task.

根据任务，推荐需运行的技能及时机：

时机	技能	原因
编码完成后	`/test-gen <file>`	为新代码生成测试
Pipeline工作完成后	`/pipeline-check`	验证节点契约和工具纯性
编码完成后	`/enforce`	捕获模式违规问题
若Database变更	`/migrate`	正确创建迁移文件
若API变更	`/sync-repos`	检查跨仓库影响
提交前	`/pre-commit`	最终检查，决定是否可提交

仅推荐与当前任务相关的技能。

Output Format

输出格式

undefined

undefined

Prepare: [short task title]

准备工作: [简短任务标题]

Scope

范围

[1-2 sentence summary of what this task involves]

[1-2句话总结任务内容]

类别

[Pipeline / API / Database / Service / Feature / Bug Fix / Refactor]

Files to Touch

需修改的文件

```
path/to/file.py
```
— what to do here
```
path/to/other.py
```
— what to do here

```
path/to/file.py
```
—— 此处需执行的操作
```
path/to/other.py
```
—— 此处需执行的操作

Checklist

检查清单

Skills to Run

需运行的技能

After coding →
```
/test-gen path/to/new_file.py
```
After coding →
```
/pipeline-check
```
(if pipeline)
Before commit →
```
/pre-commit
```

编码完成后 →
```
/test-gen path/to/new_file.py
```
编码完成后 →
```
/pipeline-check
```
（若涉及Pipeline）
提交前 →
```
/pre-commit
```

Watch Out For

注意事项

[Anything tricky or easy to miss for this specific task]

undefined

[当前任务中需注意的棘手或易遗漏事项]

undefined

Rules

规则

Read docs first, code second. The
```
docs/
```
directory and
```
AGENTS.md
```
describe architecture, file paths, and patterns. Only read source code when the docs don't answer something specific. This saves tokens and is faster.
Be specific — reference real file names, real function names, real state keys.
Don't over-scope — only include checklist items relevant to this task.
Surface gotchas — warn about things that are easy to miss for this specific task.

先读文档，后看代码。
```
docs/
```
目录和
```
AGENTS.md
```
描述了架构、文件路径和模式。仅当文档无法解答特定问题时才阅读源代码。这样可以节省token并提高效率。
具体明确 —— 引用真实的文件名、函数名、状态键。
不要过度扩大范围 —— 仅包含与当前任务相关的检查清单事项。
突出注意事项 —— 提醒当前任务中易遗漏的棘手问题。",