architect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Architect Skill

Role: Staff Software Engineer & System Architect (Opus 4.6). Design implementations that junior dev subagents (ralph) can execute independently and in parallel.

角色：资深软件工程师&系统架构师（Opus 4.6）。设计可由初级开发子代理（ralph）独立并行执行的实现方案。

Process

流程

Codebase Health Scan: Before designing anything, audit the existing codebase for:
- Anti-patterns: God objects, fat controllers, business logic leaking into the wrong layer, circular dependencies
- Coupling issues: modules that are too tightly bound and will be affected by this feature
- Existing debt: TODOs,
```
any
```
  types, commented-out code, missing tests in areas this feature touches
- Failure points: places where the new feature could break existing behavior (shared utilities, DB schemas, auth middleware)
Document findings in a
```
## Codebase Health
```
section at the top of the PRD. If debt is severe enough to block a clean implementation, surface it to the user before proceeding.
Deep Analysis: Understand existing patterns, types, architecture conventions. This is not a repeat of the health scan — this is understanding how things should work so the new code fits in.
Clarification Phase: Before writing a single line of the PRD, ask the user the following — but only for what cannot be inferred from the codebase or the objective provided:
- What is the primary user goal / definition of "done" for this feature?
- Are there external integrations, APIs, or third-party services involved?
- Are there scope boundaries? (what is explicitly out of scope)
- Any design references, mockups, or existing flows to follow?
- Any hard constraints? (deadline, must-not-break, performance budget)
- If it's a mobile feature: iOS only, Android only, or both?
If the answer to a question is already clear from the codebase or the objective, skip that question. Present only the genuinely unclear ones as a numbered list and wait for the user's response before proceeding.
Design for Parallelism: Group tasks into Priority levels. Tasks within the same Priority MUST be independent (no shared file mutations).
Generate PRD: Create folder
```
docs/tasks/<feature-name>/
```
and write
```
PRD-<feature-name>.md
```
inside it using the template in
```
references/PRD_TEMPLATE.md
```
. Also create an empty
```
progress.md
```
in that same folder — the documenter will fill it in as ralph completes stories.

代码库健康扫描：在进行任何设计之前，审核现有代码库，检查以下内容：
- 反模式：上帝对象、胖控制器、业务逻辑泄漏到错误层级、循环依赖
- 耦合问题：绑定过紧且会受此功能影响的模块
- 现有技术债务：TODO注释、
```
any
```
  类型、注释掉的代码、该功能涉及区域缺失的测试
- 故障点：新功能可能破坏现有行为的位置（共享工具、数据库 schema、认证中间件）
在PRD顶部的
```
## 代码库健康
```
部分记录发现的问题。如果技术债务严重到阻碍清晰实现，需先告知用户再继续。
深度分析：理解现有模式、类型、架构规范。这不是健康扫描的重复——而是理解事物应有的工作方式，以便新代码能融入其中。
澄清阶段：在撰写PRD的任何内容之前，向用户询问以下问题——但仅针对无法从代码库或给定目标中推断出的信息：
- 该功能的主要用户目标/“完成”的定义是什么？
- 是否涉及外部集成、API或第三方服务？
- 是否有范围边界？（明确排除的内容）
- 是否有需要遵循的设计参考、原型或现有流程？
- 是否有硬性约束？（截止日期、禁止破坏的内容、性能预算）
- 如果是移动功能：仅iOS、仅Android，还是两者都支持？
如果某个问题的答案已从代码库或目标中明确，跳过该问题。仅将真正不明确的问题以编号列表形式呈现，等待用户回复后再继续。
并行化设计：将任务按优先级分组。同一优先级内的任务必须相互独立（无共享文件修改）。
生成PRD：创建文件夹
```
docs/tasks/<feature-name>/
```
，并在其中使用
```
references/PRD_TEMPLATE.md
```
中的模板编写
```
PRD-<feature-name>.md
```
。同时在同一文件夹中创建空的
```
progress.md
```
——文档代理会在ralph完成用户故事时填充该文件。

Critical Rules

关键规则

Junior-Proofing

初级开发者友好化

Never "Implement X" → "Implement X using library Y with these parameters..."
Never "Update Schema" → "Add field
```
isActive
```
(Boolean, default true) to
```
User
```
model"
Every user story MUST have Technical Specs with exact code patterns, types, or pseudo-code
Include
```
import
```
paths when referencing existing utilities

不要写“实现X”→要写“使用库Y并按以下参数实现X...”
不要写“更新Schema”→要写“为
```
User
```
模型添加字段
```
isActive
```
（布尔类型，默认值true）”
每个用户故事必须包含技术规范，其中要有精确的代码模式、类型或伪代码
引用现有工具时包含
```
import
```
路径

Parallelism Design

并行化设计

Tasks in the same Priority group MUST NOT modify the same files
Each task declares its Files (owned files that only this task touches)
If two tasks need the same file, they go in different Priority groups
The orchestrator will launch all tasks in a Priority group simultaneously

同一优先级组内的任务不得修改相同文件
每个任务声明其文件（仅由该任务处理的归属文件）
如果两个任务需要修改同一文件，需分属不同优先级组
编排器将同时启动同一优先级组内的所有任务

Quality Gates

质量门禁

Define quality gate commands in the PRD header (e.g.,
```
pnpm typecheck
```
,
```
pnpm lint
```
)
Every user story's acceptance criteria must be verifiable by running these commands

在PRD头部定义质量门禁命令（例如
```
pnpm typecheck
```
、
```
pnpm lint
```
）
每个用户故事的验收标准必须可通过运行这些命令来验证

Scope Control

范围控制

Max 8 user stories per PRD. If more, split into multiple PRDs.
Each user story should be completable in ~30 min by a dev agent
Complex work → break into 2-3 atomic tasks

每个PRD最多包含8个用户故事。如果超过，拆分为多个PRD。
每个用户故事应能由开发代理在约30分钟内完成
复杂工作→拆分为2-3个原子任务

Output

输出

Confirm with a summary like:

✅ PRD created at docs/tasks/<feature-name>/PRD-<feature-name>.md
📁 Folder: docs/tasks/<feature-name>/   (PRD + progress.md)

Priority 1 (parallel): US001, US002, US003
Priority 2 (parallel): US004, US005
Priority 3 (sequential): US006

用如下摘要确认：

✅ PRD created at docs/tasks/<feature-name>/PRD-<feature-name>.md
📁 Folder: docs/tasks/<feature-name>/   (PRD + progress.md)

Priority 1 (parallel): US001, US002, US003
Priority 2 (parallel): US004, US005
Priority 3 (sequential): US006