context-engineering

Context Engineering

概述

在正确的时间给 agent 提供正确的信息。上下文是影响 agent 输出质量的最大单一杠杆：太少，agent 会幻觉；太多，它会失去焦点。上下文工程就是有意识地策划 agent 看到什么、何时看到，以及内容如何组织。

何时使用

• 开始新的编码会话
• Agent 输出质量正在下降（模式错误、幻觉 API、忽略约定）
• 在代码库的不同部分之间切换
• 为新项目配置 AI 辅助开发
• Agent 没有遵循项目约定

上下文层级

按从最持久到最短暂的顺序组织上下文：

┌─────────────────────────────────────┐
│  1. Rules Files (CLAUDE.md, etc.)   │ ← Always loaded, project-wide
├─────────────────────────────────────┤
│  2. Spec / Architecture Docs        │ ← Loaded per feature/session
├─────────────────────────────────────┤
│  3. Relevant Source Files            │ ← Loaded per task
├─────────────────────────────────────┤
│  4. Error Output / Test Results      │ ← Loaded per iteration
├─────────────────────────────────────┤
│  5. Conversation History             │ ← Accumulates, compacts
└─────────────────────────────────────┘

第 1 层：Rules 文件

创建一个跨会话持久存在的 rules 文件。这是你能提供的杠杆率最高的上下文。

CLAUDE.md（用于 Claude Code）：

# Project: [Name]

## Tech Stack
- React 18, TypeScript 5, Vite, Tailwind CSS 4
- Node.js 22, Express, PostgreSQL, Prisma

## Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint --fix`
- Dev: `npm run dev`
- Type check: `npx tsc --noEmit`

## Code Conventions
- Functional components with hooks (no class components)
- Named exports (no default exports)
- colocate tests next to source: `Button.tsx` → `Button.test.tsx`
- Use `cn()` utility for conditional classNames
- Error boundaries at route level

## Boundaries
- Never commit .env files or secrets
- Never add dependencies without checking bundle size impact
- Ask before modifying database schema
- Always run tests before committing

## Patterns
[One short example of a well-written component in your style]

其他工具的等价文件：

• .cursorrules 或 .cursor/rules/*.md（Cursor）
• .windsurfrules（Windsurf）
• .github/copilot-instructions.md（GitHub Copilot）
• AGENTS.md（OpenAI Codex）

第 2 层：Specs 与架构

开始一个 feature 时加载相关的 spec 章节。如果只有一节适用，就不要加载整份 spec。

高效： "这是我们 spec 中的认证章节：[auth spec content]"