Full-Stack Development Practices

MANDATORY WORKFLOW

触发此 skill 后，必须按以下步骤执行：

Step 0: Gather Requirements

确认以下信息（如用户已指定则跳过）：

1. Stack: 后端+前端语言/框架
2. Service type: API-only / 全栈单体 / 微服务
3. Database: SQL / NoSQL
4. Integration: REST / GraphQL / tRPC / gRPC
5. Real-time: SSE / WebSocket / Polling / 不需要
6. Auth: JWT / Session / OAuth / 不需要

Step 1: Architectural Decisions

基于需求做出并声明决策（每个决策一句话）：

Step 2: Scaffold with Checklist

后端服务 Checklist：

• Feature-first 项目结构
• 配置集中管理，环境变量启动时验证（fail fast）
• 类型化错误层级（非通用 Error）
• 全局错误处理中间件
• 结构化 JSON 日志 + request ID
• 数据库 Migration + 连接池
• 输入验证（Zod / Pydantic / Go validator）
• 认证中间件
• 健康检查端点（/health, /ready）
• 优雅关闭（SIGTERM）
• CORS 配置（显式 origin）
• 安全头（helmet 等）
• .env.example（不含真实密钥）

前后端集成 Checklist：

• 类型化 API Client
• Base URL 从环境变量读取
• Auth token 自动附加
• API 错误映射为用户友好消息
• Loading 状态处理
• 跨边界类型安全
• CORS 显式配置
• Refresh token 流程

Step 3: Implement

按照 references 中的模式编写代码。每完成一个模块立即验证。

Step 4: Verify

# 构建检查
cd server && npm run build
cd client && npm run build

# 冒烟测试
curl http://localhost:3000/health

# 集成检查：前端能连通后端

Step 5: Handoff

📦 交付：
- 实现的功能和端点列表
- 启动命令
- 已知限制 / 下一步建议
- 关键文件列表

7 条铁律

1. 按Feature 组织代码，不按技术层
2. Controller 不含业务逻辑
3. Service 不导入 HTTP 请求/响应类型
4. 所有配置来自环境变量，启动时验证
5. 所有错误类型化、结构化返回
6. 所有输入在边界处验证
7. 结构化 JSON 日志 + request ID

详细参考文档（按需查阅）

需要具体代码模式和深入指导时，查阅以下参考文档：

反模式速查