Context Engineering 2.0：从 Prompt 技巧到系统级上下文架构设计

<!-- .github/copilot-instructions.md -->

## 项目概述
这是一个基于 Next.js 14 + TypeScript 的全栈 SaaS 平台。

## 编码规范
- 所有组件使用函数式组件 + Hooks，禁止 class 组件
- 样式方案：Tailwind CSS + CSS Modules，禁止内联样式
- 状态管理：Zustand（全局）+ React Query（服务端）
- 所有 API 调用通过 `src/lib/api-client.ts` 封装

## 架构约束
- 页面组件放在 `app/` 目录（App Router）
- 业务逻辑封装在 `src/services/` 下
- 数据库操作通过 Prisma ORM，禁止原始 SQL

## 禁止事项
- 不要使用 `any` 类型
- 不要在组件中直接调用 fetch
- 不要使用 moment.js，统一使用 date-fns

<!-- .github/prompts/code-review.prompt.md -->

你是一个严格的代码审查员。请按以下维度审查代码变更：

### 安全性
- 检查是否存在 SQL 注入、XSS、CSRF 风险
- 检查敏感信息是否暴露（API Key、密码等）

### 性能
- 检查是否有 N+1 查询
- 检查 React 组件是否存在不必要的重渲染

### 可维护性
- 函数是否超过 50 行
- 是否遵循项目的命名约定

### 输出格式
对每个问题，按 [严重/警告/建议] 分类，并给出修复建议。

<!-- .github/prompts/api-endpoint.prompt.md -->

请为以下功能创建 REST API 端点：

### 要求
- 使用 Next.js Route Handler (app/api/)
- 输入验证使用 Zod schema
- 错误处理遵循 RFC 7807 Problem Details 格式
- 包含 rate limiting 中间件
- 编写对应的集成测试

### 模板
请参考 `app/api/users/route.ts` 的实现模式。

<!-- .github/agents/database-expert.md -->

## 角色
你是数据库架构专家，精通 PostgreSQL 和 Prisma ORM。

## 能力范围
- 设计和优化数据库 schema
- 编写高效的数据库查询
- 分析和优化慢查询
- 设计数据迁移策略

## 约束
- 所有 schema 变更必须通过 Prisma Migration
- 索引策略必须考虑读写比
- 敏感字段必须加密存储
- 禁止使用 CASCADE DELETE（使用软删除）

## 可访问工具
- @database: 查询数据库 schema
- @terminal: 执行 prisma 命令

<!-- agents.md -->

# Project: QubitTool

## 1. Identity（身份定义）
你是 QubitTool 项目的核心开发者。这是一个面向开发者的在线工具平台，
基于 Next.js + React 构建，支持中英文双语。

## 2. Knowledge（知识边界）
- 熟悉项目的文件结构：`src/` 下是前端代码，`content/` 下是内容文件
- 了解 Ant Design 组件库的用法
- 知道项目使用 next-i18next 进行国际化

## 3. Boundaries（行为边界）
- 不要修改 `src/core/tool-definitions.js`，除非明确要求
- 不要删除任何现有的测试用例
- 不要引入新的第三方依赖，除非讨论后确认

## 4. Workflow（工作流偏好）
- 修改前先阅读相关文件，理解现有模式
- 新增功能时，先更新 i18n 文件，再写组件
- 所有改动必须通过 `npm run lint` 检查

## 5. Communication（沟通风格）
- 修改超过 3 个文件时，先列出修改计划
- 遇到不确定的架构决策时，提供 2-3 个方案让我选择
- 用中文回复

项目根目录/
├── .trae/
│   └── rules/
│       ├── code-style.md      # 编码风格规范
│       ├── git-commit.md      # Git 提交规范
│       ├── architecture.md    # 架构约束
│       └── testing.md         # 测试规范

<!-- .trae/rules/code-style.md -->

# 编码风格规范

## 组件规范
- 使用函数式组件 + Hooks
- Props 必须解构
- 事件处理函数使用 handleXxx 命名

## 导入顺序
1. React 及相关
2. 第三方库
3. 项目内部组件
4. Hooks
5. 工具函数 / 常量
6. 样式（最后）

项目根目录/
├── .cursor/
│   └── rules/
│       ├── global.mdc          # 全局规则（始终生效）
│       ├── react-components.mdc # 匹配 *.tsx 文件时生效
│       └── api-routes.mdc      # 匹配 app/api/** 时生效

---
description: React 组件开发规范
globs: ["src/components/**/*.tsx", "src/pages/**/*.tsx"]
---

## 组件规范
- 使用 Ant Design 组件库
- 所有文本使用 useTranslation hook
- 样式使用 CSS Modules
- 性能敏感组件使用 React.memo

<!-- .github/copilot-instructions.md (组织级模板) -->

## 安全规范（强制）
- 所有用户输入必须经过校验和转义
- 禁止在代码中硬编码密钥、Token、密码
- 数据库查询必须使用参数化查询
- API 响应不得包含内部错误堆栈

## 合规要求（强制）
- 日志中不得记录 PII（个人身份信息）
- 所有 HTTP API 必须支持 HTTPS
- 文件上传必须校验 MIME 类型和大小

## 代码质量（推荐）
- 函数单一职责，不超过 40 行
- 测试覆盖率目标：核心业务 > 80%
- 提交信息遵循 Conventional Commits 规范

<!-- 项目根目录/agents.md -->

# QubitTool 项目规则

## 技术栈
- Framework: Next.js 14 (Pages Router)
- UI: Ant Design 5 + CSS Modules
- i18n: next-i18next
- 部署: Vercel

## 文件结构约定
- `src/pages/tools/[slug].tsx` — 工具页面入口
- `src/core/tool-definitions.js` — 工具注册表（单一数据源）
- `content/blog/posts/{lang}/*.md` — 博客文章
- `public/locales/{lang}/*.json` — 多语言文件

## 核心模式
- 新增工具时，必须同步更新 tool-definitions.js
- 所有用户可见文本必须通过 t() 函数国际化
- 使用 recordCount() 进行页面统计打点

<!-- ~/.config/cursor/rules/personal.mdc -->
<!-- 或通过 IDE 的 User Settings 配置 -->

## 沟通偏好
- 用中文回复
- 修改代码前先说明修改计划
- 给出 2-3 个方案时，标注你的推荐

## 代码风格微调
- 我偏好显式类型标注（即使 TypeScript 能推断）
- 变量命名偏好描述性名称而非缩写
- 注释使用中文

个人层 > 项目层 > 组织层

┌─────────────────────────────────────────────┐
│              AI 的上下文窗口                   │
│                                             │
│  ┌─────────────┐  ┌──────────────────────┐  │
│  │ 静态上下文    │  │ 动态上下文（MCP）      │  │
│  │             │  │                      │  │
│  │ agents.md   │  │ @database → Schema   │  │
│  │ rules/*.md  │  │ @github → Issues     │  │
│  │ prompts.md  │  │ @docs → API 文档      │  │
│  │             │  │ @terminal → 运行结果   │  │
│  └─────────────┘  └──────────────────────┘  │
│                                             │
│  ┌──────────────────────────────────────┐   │
│  │ 用户当前指令 (Prompt)                  │   │
│  └──────────────────────────────────────┘   │
└─────────────────────────────────────────────┘

项目根目录/
├── .github/
│   ├── copilot-instructions.md
│   └── prompts/
│       ├── code-review.prompt.md
│       ├── api-endpoint.prompt.md
│       └── bug-fix.prompt.md
├── .cursor/
│   └── rules/
│       └── project.mdc
├── .trae/
│   └── rules/
│       └── code-style.md
└── agents.md

my-saas-app/
├── .github/
│   ├── copilot-instructions.md    # Copilot 全局指令
│   └── prompts/
│       ├── new-feature.prompt.md  # 新功能开发模板
│       ├── code-review.prompt.md  # 代码审查模板
│       ├── db-migration.prompt.md # 数据库迁移模板
│       └── test-gen.prompt.md     # 测试生成模板
├── .cursor/
│   └── rules/
│       ├── global.mdc             # Cursor 全局规则
│       ├── frontend.mdc           # 前端文件匹配规则
│       └── backend.mdc            # 后端文件匹配规则
├── .trae/
│   └── rules/
│       ├── code-style.md          # TRAE 编码规范
│       └── git-commit.md          # TRAE Git 规范
├── agents.md                      # 通用项目规则
├── CLAUDE.md                      # Claude 项目记忆
└── src/
    └── ...