第 18 章：Context Engineering：让 AI 真正读懂你的代码库

# 项目：AI Agent Engineering Toolbox
# 技术栈：Next.js + TypeScript + Cloudflare Workers + D1

## 通用规则
- 所有新代码使用 TypeScript，不使用 any。
- 优先使用函数组件，React 组件默认导出。
- API 路由统一放在 app/api/[...]/route.ts。
- 数据库操作统一封装到 lib/db.ts，不在 route 里直接写 SQL。

## 命名约定
- 文件使用 kebab-case。
- React 组件使用 PascalCase。
- 工具函数使用 camelCase。

## 禁止项
- 不要在代码中硬编码 API key。
- 不要在路由中直接解析用户输入的 JSON，使用 Zod 校验。
- 不要引入新的运行时依赖而不说明理由。

# AGENTS.md

## 目标
让后续智能体快速确认当前主任务、系统入口和验证方式。

## 阅读顺序
1. `docs/agent-context.md`
2. `README.md`
3. 当前任务相关的 `docs/plans/*` 和 `docs/progress/*`
4. 入口层、业务层、数据层、测试层

## 代码边界
- `apps/web`：前端 Next.js 应用
- `packages/ui`：共享组件库
- `packages/utils`：共享工具函数
- `content/courses`：课程内容 Markdown

## 验证方式
- 前端改动：npm run dev + 浏览器人工检查
- 后端改动：npm run test
- 文档改动：检查路径和链接

# CLAUDE.md

## 项目结构
- `apps/web`：Next.js 应用
- `packages/ui`：共享 UI 组件
- `packages/utils`：共享工具函数

## 常用命令
- 安装依赖：`npm install`
- 本地开发：`npm run dev`
- 运行测试：`npm run test`
- 构建：`npm run build`

## 测试入口
- 单元测试：`packages/utils/**/*.test.ts`
- 集成测试：`apps/web/tests/integration/**/*.test.ts`

## 注意事项
- 所有 API 调用必须经过 `lib/api-client.ts` 封装。
- 环境变量通过 `process.env` 读取，开发环境使用 `.env.local`。

项目：ai_engineer_toolbox
├── apps/web/           # Next.js 前端
│   ├── app/            # 路由与页面
│   ├── components/     # 业务组件
│   └── lib/            # 工具与 API 客户端
├── packages/ui/        # 共享 UI 组件
├── packages/utils/     # 共享工具函数
├── content/courses/    # 课程 Markdown 内容
├── docs/               # 项目文档
└── scripts/            # 脚本

关键约定：
- API 路由统一在 apps/web/app/api/...
- 共享组件通过 @repo/ui 引入
- 课程章节统一放在 content/courses/beginner-courses/ai-agent-engineering/lectures/

# symbol_index.py
{
    "create_order": {
        "type": "function",
        "file": "apps/web/app/api/orders/route.ts",
        "line": 23,
        "references": ["lib/order-service.ts", "lib/db.ts"],
        "summary": "创建订单的 API 入口，校验输入并调用 order-service"
    },
    "OrderService": {
        "type": "class",
        "file": "lib/order-service.ts",
        "line": 10,
        "references": ["apps/web/app/api/orders/route.ts"],
        "summary": "订单业务逻辑封装"
    }
}

from sentence_transformers import SentenceTransformer
import numpy as np

model = SentenceTransformer("all-MiniLM-L6-v2")

def embed(text: str) -> np.ndarray:
    return model.encode(text)

def search(query: str, chunks: list[str], top_k: int = 5):
    query_vec = embed(query)
    chunk_vecs = np.array([embed(c) for c in chunks])
    scores = chunk_vecs @ query_vec
    top_indices = np.argsort(scores)[::-1][:top_k]
    return [chunks[i] for i in top_indices]

import { pipeline } from "@xenova/transformers";

const embedder = await pipeline("feature-extraction", "Xenova/all-MiniLM-L6-v2");

async function embed(text: string): Promise<number[]> {
  const result = await embedder(text, { pooling: "mean", normalize: true });
  return Array.from(result.data);
}

function cosineSimilarity(a: number[], b: number[]): number {
  const dot = a.reduce((sum, val, i) => sum + val * b[i], 0);
  const normA = Math.sqrt(a.reduce((sum, val) => sum + val * val, 0));
  const normB = Math.sqrt(b.reduce((sum, val) => sum + val * val, 0));
  return dot / (normA * normB);
}

package main

import (
    "context"
    "fmt"

    "github.com/tmc/langchaingo/embeddings"
    "github.com/tmc/langchaingo/llms/openai"
)

func main() {
    llm, err := openai.New()
    if err != nil {
        panic(err)
    }

    embedder, err := embeddings.NewEmbedder(llm)
    if err != nil {
        panic(err)
    }

    vectors, err := embedder.EmbedQuery(context.Background(), "订单创建流程")
    if err != nil {
        panic(err)
    }

    fmt.Printf("向量维度：%d\n", len(vectors))
}

import dev.langchain4j.model.embedding.EmbeddingModel;
import dev.langchain4j.model.embedding.onnx.allminilml6v2.AllMiniLmL6V2EmbeddingModel;

public class CodeSearch {
    public static void main(String[] args) {
        EmbeddingModel model = new AllMiniLmL6V2EmbeddingModel();
        var response = model.embed("订单创建流程");
        System.out.println("向量维度：" + response.content().vector().length);
    }
}