Back to Details

architect

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Read: docs/PRD.md, docs/research/VERDICT.md, docs/SCREENS.md, and all files in wireframes/
You are a Senior Software Architect. This is a pre-implementation phase only. Do not write any feature code.
━━━ OUTPUT 1: STACK DECISION (docs/STACK.md) ━━━
Recommend a tech stack. Justify every choice in exactly one sentence. Default to boring, proven technology. Resist novelty.
Consider: complexity of the PRD, offline requirements, team size (assume solo unless stated), performance needs, and deployment simplicity.
Structure:
  • Frontend framework + why
  • Styling approach + why
  • Backend approach (or "none needed" if client-only) + why
  • Database (or "none needed") + why
  • Auth approach + why
  • Hosting recommendation + why
  • Unit test runner + why
  • E2E test runner (Playwright — always Playwright) + why
━━━ OUTPUT 2: DATA MODEL (docs/DATA_MODEL.md) ━━━
List every entity the product manages. For each entity:
  • Fields, types, constraints
  • Relationships to other entities
  • Which screen(s) display or modify this entity
Keep it simple. Normalise only what needs normalising.
━━━ OUTPUT 3: CLAUDE.md (project root) ━━━
This is the most important file you will write. It persists across every future session. Write it carefully.
阅读：docs/PRD.md、docs/research/VERDICT.md、docs/SCREENS.md，以及wireframes/目录下的所有文件
你是一名资深软件架构师，当前处于预实现阶段，请勿编写任何功能代码。
━━━ 输出1：技术栈决策（docs/STACK.md） ━━━
推荐一套技术栈，每项选择需用一句话说明理由。优先选择成熟、经过验证的技术，避免使用新颖但未经考验的技术。
需考虑因素：PRD的复杂度、离线需求、团队规模（除非特别说明，默认按单人团队考虑）、性能需求以及部署的简易性。
结构：
  • 前端框架 + 选择理由
  • 样式方案 + 选择理由
  • 后端方案（若仅需客户端实现则填“无需后端”） + 选择理由
  • 数据库（若无需则填“无需数据库”） + 选择理由
  • 认证方案 + 选择理由
  • 托管方案推荐 + 选择理由
  • 单元测试运行器 + 选择理由
  • E2E测试运行器（必须使用Playwright） + 选择理由
━━━ 输出2：数据模型（docs/DATA_MODEL.md） ━━━
列出产品管理的所有实体。 每个实体需包含：
  • 字段、类型、约束
  • 与其他实体的关系
  • 哪些页面会展示或修改该实体
保持简洁，仅对必要的内容进行规范化处理。
━━━ 输出3：CLAUDE.md（项目根目录） ━━━
这是你需要撰写的最重要的文件，它会在后续所有会话中持续生效，请仔细撰写。

CLAUDE.md

CLAUDE.md

What We Are Building

我们正在构建什么

[One paragraph from PRD vision]
[来自PRD愿景的一段内容]

Stack

技术栈

[From STACK.md — 6-8 bullet points]
[来自STACK.md的6-8个要点]

Project Structure

项目结构

[Folder tree with one-line description of each folder's purpose]
[文件夹树状结构，每个文件夹配一行说明其用途]

Commands

命令

npm run dev — start development server npm run build — production build npm run test — run unit + integration tests npm run test:e2e — run Playwright E2E suite npm run test:visual — run visual regression tests npm run coverage — coverage report npm run lint — ESLint + TypeScript check
npm run dev — 启动开发服务器 npm run build — 生产环境构建 npm run test — 运行单元测试+集成测试 npm run test:e2e — 运行Playwright E2E测试套件 npm run test:visual — 运行视觉回归测试 npm run coverage — 生成覆盖率报告 npm run lint — 执行ESLint + TypeScript检查

Non-Negotiable Rules

不可妥协的规则

  1. Every feature must have unit + integration + E2E tests before it is considered complete. No exceptions. No "I'll add tests later."
  2. Playwright tests use ONLY semantic locators: getByRole(), getByLabel(), getByText(), getByTestId() Never CSS class selectors. Never XPath.
  3. The test suite only grows. Tests are never deleted — only updated.
  4. Every bug fix ships with a regression test that first reproduces the bug.
  5. Visual snapshots are the design truth. Unintentional visual changes are treated as regressions.
  6. A feature with a quality score below 85 is not done.
  1. 每个功能在完成前必须具备单元测试+集成测试+E2E测试，无例外，不允许“稍后再补测试”。
  2. Playwright测试仅使用语义化定位器： getByRole()、getByLabel()、getByText()、getByTestId() 禁止使用CSS类选择器，禁止使用XPath。
  3. 测试套件只能扩充，永远不能删除测试——仅可更新测试。
  4. 每个Bug修复必须附带一个能复现该Bug的回归测试。
  5. 视觉快照是设计的唯一标准，非预期的视觉变更视为回归问题。
  6. 质量评分低于85分的功能不算完成。

Coding Conventions

编码规范

[Language-specific: naming, file organisation, import order, etc.]
[针对具体语言：命名规则、文件组织、导入顺序等]

Definition of Done Checklist

完成定义检查清单

[ ] Feature works per acceptance criteria in PRD [ ] Unit tests written and passing (≥80% line coverage) [ ] Integration tests written and passing [ ] Playwright E2E test covers happy path + at least 2 edge cases [ ] Visual regression snapshot created or updated [ ] No TypeScript errors (if applicable) [ ] No lint errors [ ] QA quality score ≥ 85
[ ] 功能符合PRD中的验收标准 [ ] 已编写并通过单元测试（代码覆盖率≥80%） [ ] 已编写并通过集成测试 [ ] Playwright E2E测试覆盖主流程+至少2个边缘场景 [ ] 已创建或更新视觉回归测试快照 [ ] 无TypeScript错误（若适用） [ ] 无代码检查错误 [ ] QA质量评分≥85分

Known Patterns

已采用的架构模式

[Document any architectural patterns chosen, e.g.: "Use Repository pattern for all data access" "All API calls go through src/lib/api.ts — never fetch() directly in components"]

━━━ OUTPUT 4: MCP CONFIG (.mcp.json) ━━━
Create .mcp.json at project root with Playwright MCP configured for interactive browser testing. This is REQUIRED for /test-ui and /qa-run:
{ "mcpServers": { "playwright": { "command": "npx", "args": [ "@playwright/mcp@latest", "--caps", "screenshot,pdf,testing" ] } } }
The "testing" cap enables: browser_generate_playwright_test, browser_generate_locator, browser_verify_text_visible, browser_verify_element_visible, browser_verify_value.
The "screenshot" cap enables: browser_take_screenshot for visual verification.
If the project needs GitHub integration, add: { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_TOKEN" } } }
━━━ OUTPUT 5: PROJECT SCAFFOLD ━━━
Execute:
  1. Create all folders per the structure in CLAUDE.md
  2. Initialise package.json / equivalent
  3. Install all dependencies
  4. Configure: ESLint, Prettier, TypeScript (if applicable)
  5. Configure Vitest (or chosen unit runner) with coverage reporting
  6. Configure Playwright with:
    • Default project (Chromium, 1280x720)
    • Mobile project (375x667, mobile emulation)
    • Visual project (for snapshot tests)
  7. Create .mcp.json with Playwright MCP (see OUTPUT 4)
  8. Create .github/workflows/qa.yml (CI pipeline)
  9. Create qa/browser-tests/ directory for Playwright MCP test artifacts
  10. Write a single smoke test: "dev server starts and returns 200"
  11. Run the smoke test. Confirm it passes.
When complete, say: "Architecture complete. CLAUDE.md written. Project scaffolded. Playwright MCP configured. Smoke test passing. Ready to build features — run /build [feature-name] using the P0 features from the PRD, in order."

[记录所选择的架构模式，例如： “所有数据访问使用Repository模式” “所有API调用通过src/lib/api.ts发起——禁止在组件中直接使用fetch()”]

━━━ 输出4：MCP配置（.mcp.json） ━━━
在项目根目录创建.mcp.json文件，配置Playwright MCP以支持交互式浏览器测试。这是运行/test-ui和/qa-run命令的必要条件：
{ "mcpServers": { "playwright": { "command": "npx", "args": [ "@playwright/mcp@latest", "--caps", "screenshot,pdf,testing" ] } } }
其中“testing”权限启用：browser_generate_playwright_test、 browser_generate_locator、browser_verify_text_visible、 browser_verify_element_visible、browser_verify_value。
“screenshot”权限启用：browser_take_screenshot用于视觉验证。
如果项目需要GitHub集成，添加： { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_TOKEN" } } }
━━━ 输出5：项目脚手架搭建 ━━━
执行以下步骤：
  1. 根据CLAUDE.md中的结构创建所有文件夹
  2. 初始化package.json或对应配置文件
  3. 安装所有依赖
  4. 配置ESLint、Prettier、TypeScript（若适用）
  5. 配置Vitest（或所选的单元测试运行器）并启用覆盖率报告
  6. 配置Playwright：
    • 默认项目（Chromium，分辨率1280x720）
    • 移动端项目（分辨率375x667，启用移动端模拟）
    • 视觉测试项目（用于快照测试）
  7. 创建包含Playwright MCP配置的.mcp.json文件（见输出4）
  8. 创建.github/workflows/qa.yml（CI流水线）
  9. 创建qa/browser-tests/目录用于存放Playwright MCP测试产物
  10. 编写一个简单的冒烟测试：“开发服务器启动并返回200状态码”
  11. 运行冒烟测试，确认测试通过。
完成后，请输出： "架构搭建完成。CLAUDE.md已撰写。项目脚手架已搭建。 Playwright MCP已配置。冒烟测试通过。 准备开始构建功能——请使用PRD中的P0级功能，按顺序运行/build [功能名称]命令。"