Quetrex架构执行器Skill quetrex-architect

---

name: quetrex-architect description: 在Quetrex中实现新功能时使用。确保遵循TDD、TypeScript严格模式、Next.js App Router模式、ShadCN UI组件和安全最佳实践。已更新至2025年11月标准。 allowed-tools: Read, Grep, Glob

Quetrex架构执行器

使用时机

• 创建新功能
• 重构现有代码
• 审查PR
• 确保模式合规

执行流程

1. 阅读CLAUDE.md获取项目上下文
2. 阅读.quetrex/memory/patterns.md获取架构模式（如果存在）
3. 检查功能是否使用正确模式：
   • TypeScript严格模式（无any类型，无@ts-ignore）
   • API路由使用Zod验证
   • 服务器组件与客户端组件区分
   • 流式传输的SSE模式
4. 如果发现违规，解释正确模式
5. 指导遵循TDD的实现

需要执行的模式

TypeScript严格模式

// ✅ 正确做法：显式类型
function calculateTotal(items: CartItem[]): number {
  return items.reduce((sum, item) => sum + item.price, 0)
}

// ❌ 错误做法：使用'any'
function processData(data: any) { }

// ✅ 正确做法：使用类型守卫
function isCartItem(obj: unknown): obj is CartItem {
  return typeof obj === 'object' && obj !== null && 'price' in obj
}

Next.js App Router模式

// ✅ 正确做法：服务器组件（默认）
export default async function DashboardPage() {
  const projects = await prisma.project.findMany()
  return <ProjectList projects={projects} />
}

// ✅ 正确做法：客户端组件（需要时）
'use client'
export function InteractiveButton() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}

// ❌ 错误做法：异步客户端组件
'use client'
export default async function BadComponent() { } // 错误

Zod验证

// ✅ 正确做法：验证所有API输入
import { z } from 'zod'

const createProjectSchema = z.object({
  name: z.string().min(1).max(100),
  description: z.string().optional(),
})

export async function POST(request: Request) {
  const body = await request.json()
  const validated = createProjectSchema.parse(body) // 无效时抛出错误
  // ... 使用已验证的数据
}

// ❌ 错误做法：未验证的输入
export async function POST(request: Request) {
  const { name, description } = await request.json() // 无验证
}

ShadCN UI模式（2025年11月标准）

// ✅ 正确做法：使用ShadCN UI组件
import { Button } from "@/components/ui/button"
import { Dialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog"
import { Form, FormField, FormItem, FormLabel, FormControl } from "@/components/ui/form"

// ✅ 正确做法：使用带asChild的DialogTrigger
<DialogTrigger asChild>
  <Button>打开</Button>
</DialogTrigger>

// ❌ 错误做法：不使用ShadCN创建自定义按钮
<button className="px-4 py-2 bg-blue-500">错误</button>

// ✅ 正确做法：使用React Hook Form + Zod的Form组件
const form = useForm<z.infer<typeof schema>>({
  resolver: zodResolver(schema),
})

<Form {...form}>
  <FormField ... />
</Form>

// ❌ 错误做法：使用非受控表单
<form>
  <input name="email" /> {/* 无验证 */}
</form>

→ 参见： shadcn-ui-patterns技能获取完整组件库

安全模式

// ❌ 错误做法：硬编码密钥
const apiKey = 'sk_live_abc123'

// ✅ 正确做法：环境变量
const apiKey = process.env.OPENAI_API_KEY
if (!apiKey) throw new Error('OPENAI_API_KEY未配置')

// ❌ 错误做法：SQL注入
const query = `SELECT * FROM users WHERE email = '${email}'`

// ✅ 正确做法：参数化查询（Drizzle）
const user = await db.query.users.findFirst({ where: eq(users.email, email) })

TDD要求

1. 先写测试
2. 验证测试失败
3. 编写实现
4. 验证测试通过
5. 按需重构

覆盖率阈值

• 总体：75%+
• 业务逻辑（src/services/）：90%+
• 工具函数（src/utils/）：90%+
• UI组件：60%+

需要捕获的常见错误

• 使用’any’类型（建议显式类型或unknown）
• 使用@ts-ignore（建议修复根本问题）
• 异步客户端组件（建议使用服务器组件或移除async）
• API路由缺少Zod验证
• 硬编码密钥（建议使用环境变量）
• 生产代码中使用console.log（建议使用适当的日志记录器）

输出格式

发现违规时：

1. 列出每个违规及其文件和行号
2. 解释为何违规
3. 展示正确模式
4. 提供修复代码示例