define-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Define Architecture

定义架构

Define durable, easy-to-change architecture defaults for TypeScript apps.

为TypeScript应用定义持久化、易于变更的架构默认规则。

How to use this skill

如何使用此Skill

Determine context:
- New codebase: follow
```
Architecture setup workflow
```
  .
- Existing codebase: follow
```
Adoption workflow
```
  .
Produce an architecture brief using
```
Output template
```
.
Run
```
Validation loop
```
before finalizing.

Load references only when needed:

Stack defaults: references/stack-defaults.md
Shipping and rollout: references/shipping-practices.md
Engineering quality checklists: references/craftsmanship.md

确定上下文：
- 新代码库：遵循
```
架构设置工作流
```
  。
- 现有代码库：遵循
```
适配工作流
```
  。
使用
```
输出模板
```
生成架构概要。
最终确定前运行
```
验证循环
```
。

仅在需要时加载参考资料：

技术栈默认配置：references/stack-defaults.md
交付与发布：references/shipping-practices.md
工程质量检查清单：references/craftsmanship.md

Architecture setup workflow

架构设置工作流

Define constraints first:
- Product scope, team size, compliance/security needs, expected scale.
- Deployment targets and required integrations.
Choose repo shape:
- Use
```
apps/
```
  for deployable surfaces (
```
api
```
  ,
```
web
```
  ,
```
admin
```
  ).
- Use
```
packages/
```
  for shared libraries (
```
shared
```
  ,
```
ui
```
  ,
```
icons
```
  ,
```
auth
```
  ,
```
proto
```
  ).
Define backend module contracts:
- ```
handler
```
  : transport only.
- ```
service
```
  : business orchestration.
- ```
dao
```
  : database access only.
- ```
mapper
```
  : DB/proto/domain transformations.
- ```
constants
```
  and
```
types
```
  : module-local contracts.
Define request context and middleware:
- Use AsyncLocalStorage-backed
```
RequestContext
```
  .
- Initialize context in every entrypoint (RPC, HTTP, jobs, CLI).
- Read context via
```
getContext()
```
  ; do not thread context params through business functions.
- Require route policy per RPC method and register services through
```
registerServiceWithPolicies
```
  .
- Keep auth, logging, errors, and context in shared middleware.
Define frontend boundaries:
- Default to Server Components; add
```
"use client"
```
  only for client-only behavior.
- Use TanStack/Connect Query for server state.
- Use MobX only for cross-cutting client state that cannot live in component state.
- Apply
```
implement-frontend
```
  for forms, hooks, and type-safe UI mappings.
Define testing and release expectations:
- Backend TDD loop: Red -> Green -> Refactor.
- Unit tests stay DB-free; integration and E2E tests run in parallel with dynamic IDs.
- Release in small, reversible steps with a rollback plan.

首先定义约束条件：
- 产品范围、团队规模、合规/安全需求、预期规模。
- 部署目标及所需集成。
选择仓库结构：
- 使用
```
apps/
```
  存放可部署服务（
```
api
```
  、
```
web
```
  、
```
admin
```
  ）。
- 使用
```
packages/
```
  存放共享库（
```
shared
```
  、
```
ui
```
  、
```
icons
```
  、
```
auth
```
  、
```
proto
```
  ）。
定义后端模块契约：
- ```
handler
```
  ：仅负责传输层。
- ```
service
```
  ：业务编排。
- ```
dao
```
  ：仅负责数据库访问。
- ```
mapper
```
  ：数据库/proto/领域模型转换。
- ```
constants
```
  和
```
types
```
  ：模块本地契约。
定义请求上下文与中间件：
- 使用基于AsyncLocalStorage的
```
RequestContext
```
  。
- 在每个入口点（RPC、HTTP、任务、CLI）初始化上下文。
- 通过
```
getContext()
```
  读取上下文；不要在业务函数中传递上下文参数。
- 每个RPC方法都需要路由策略，并通过
```
registerServiceWithPolicies
```
  注册服务。
- 将认证、日志、错误处理和上下文管理放在共享中间件中。
定义前端边界：
- 默认使用Server Components；仅在需要纯客户端行为时添加
```
"use client"
```
  。
- 使用TanStack/Connect Query管理服务端状态。
- 仅在无法使用组件状态的跨端客户端状态场景下使用MobX。
- 应用
```
implement-frontend
```
  处理表单、钩子和类型安全的UI映射。
定义测试与发布预期：
- 后端TDD循环：红 -> 绿 -> 重构。
- 单元测试不依赖数据库；集成测试和E2E测试使用动态ID并行运行。
- 以小型、可回滚的步骤发布，并制定回滚计划。

Adoption workflow (existing codebase)

适配工作流（现有代码库）

Map current architecture and pain points.
Select the smallest set of changes that enforce clear module boundaries.
Migrate one vertical slice first.
Add guardrails (lint/type/test checks) to prevent regression.
Roll out module-by-module.

梳理当前架构与痛点。
选择最小的变更集以明确模块边界。
首先迁移一个垂直切片。
添加防护措施（lint/类型/测试检查）防止回退。
逐个模块逐步推广。

Stack defaults

技术栈默认配置

Use references/stack-defaults.md as the default baseline. Deviate only when constraints require it.

以references/stack-defaults.md为默认基准。仅在约束条件要求时才偏离。

Validation loop

验证循环

Run this loop before finalizing architecture decisions:

Verify consistency:
- Naming, module boundaries, and middleware rules are applied the same way across services.

Verify quality gates:

```
npm run lint
```
```
npm run check-types
```
```
npm run test --workspace=<pkg>
```
(or equivalent targeted tests)

Verify operability:
- Observability, health checks, and rollback path are defined.
If any check fails:
- Fix the architecture brief or conventions.
- Re-run the loop.

在最终确定架构决策前运行此循环：

验证一致性：
- 命名、模块边界和中间件规则在所有服务中应用一致。

验证质量门：

```
npm run lint
```
```
npm run check-types
```
```
npm run test --workspace=<pkg>
```
（或等效的定向测试）

验证可操作性：
- 定义可观测性、健康检查和回滚路径。
若任何检查失败：
- 修复架构概要或规范。
- 重新运行循环。

Output template

输出模板

Use this structure for architecture recommendations:

markdown

undefined

使用以下结构生成架构建议：

markdown

undefined

Architecture brief

架构概要

Context and constraints

上下文与约束条件

Repo shape

仓库结构

Backend module contracts

后端模块契约

Request context and middleware policy

请求上下文与中间件策略

Frontend boundaries

前端边界

Testing strategy

测试策略

Rollout and rollback plan

发布与回滚计划

Open risks and follow-ups

未解决风险与后续工作

undefined

undefined

Skill handoffs

Skill交接

Use
```
implement-frontend
```
when implementing forms, hooks, and typed UI mappings.
Use
```
audit-ui
```
for final UI quality checks.
Use
```
ui-animation
```
for motion-specific guidance.

实现表单、钩子和类型安全UI映射时使用
```
implement-frontend
```
。
最终UI质量检查使用
```
audit-ui
```
。
动效相关指导使用
```
ui-animation
```
。

Conventions

规范

Prefer
```
interface
```
over
```
type
```
for object contracts.
Use
```
import type
```
for types.
Keep formatting consistent (2-space indentation, double quotes, semicolons, 100-character line width).

对象契约优先使用
```
interface
```
而非
```
type
```
。
使用
```
import type
```
导入类型。
保持格式一致（2空格缩进、双引号、分号、100字符行宽）。