Claude Code 上下文工程实战：让 AI 真正理解你的项目
| 实战与进阶

Claude Code 上下文工程实战：让 AI 真正理解你的项目

#Claude Code #上下文工程 #AI编程 #系统架构

AI 编程最大的痛点不是模型不够聪明，而是它不懂你的项目。

上下文工程（Context Engineering）的核心思想：把项目知识系统化地喂给 AI，让它像老员工一样理解业务。

核心理念

为什么需要上下文工程？

直接让 Claude 写代码，它只能基于通用知识生成。但你的项目有：

  • 特定的技术栈和框架约定
  • 独特的业务逻辑和领域概念
  • 团队的编码规范和设计模式

上下文工程就是把这些”隐性知识”显性化，让 AI 能够访问和理解。

两个核心启发

DeepWiki 思路：把静态文档变成可对话的知识库

  • 自然语言查询代码库
  • AI 深度索引和语义检索
  • 文档随代码自动更新

Context7 思路：为 LLM 优化的上下文协议

  • MCP 协议标准化
  • 动态维护开发上下文
  • 跨工具无缝协作

CleanShot 2026-01-13 at 16.36.47.png

实施步骤

第一步：建立项目基线

创建 AIGC/context_base.yaml，记录项目的核心信息：

# 项目基线文档
project_info:
  name: "客户管理系统"
  version: "1.0.0"
  framework: "Spring Boot + Vue3"

tech_stack:
  backend:
    - "Spring Boot 3.2"
    - "MySQL 8.0"
    - "Redis 7.0"
  frontend:
    - "Vue 3.4"
    - "TypeScript 5.0"
    - "Ant Design Vue"

# 核心业务实体
domain_knowledge:
  entities:
    - name: "客户"
      attributes: ["姓名", "联系方式", "会员等级"]
      relations:
        - target: "订单"
          type: "一对多"
    - name: "订单"
      attributes: ["订单号", "金额", "状态"]

# 代码生成模式
code_patterns:
  - pattern: "CRUD标准流程"
    steps:
      - "识别业务实体"
      - "确定字段和验证规则"
      - "生成 Entity-Service-Controller"

第二步：建立推理基线

创建 AIGC/reasoning_baseline.yaml，记录决策历史：

# 推理基线
project_context:
  current_stage: "需求分析"

# 决策历史（让 AI 理解为什么这样做）
decision_history:
  - decision: "采用 Spring Boot 框架"
    reasoning: "团队熟悉，生态成熟"
    alternatives: ["Spring Boot", "Quarkus", "Micronaut"]
    date: "2025-01-15"

  - decision: "使用 Redis 做缓存"
    reasoning: "高并发场景需要，团队有运维经验"
    date: "2025-01-16"

# 质量要求
quality_metrics:
  code_coverage: ">80%"
  api_response_time: "<200ms"

第三步：定义需求模板

使用 EARS（Easy Approach to Requirements Syntax）格式，让需求更精确：

# 需求模板
requirement:
  id: "REQ_001"
  title: "客户列表查询"

  # EARS 格式需求描述
  specification: |
    WHEN 用户进入客户管理页面
    IF 用户有查看权限
    THEN 系统显示客户列表
    AND 支持按姓名、手机号搜索

  # BDD 验收场景
  scenarios:
    - given: "用户已登录且有权限"
      when: "访问客户列表页面"
      then: "显示分页的客户数据"

    - given: "用户输入搜索关键词"
      when: "点击搜索按钮"
      then: "显示匹配的客户记录"

  # 实现提示
  hints:
    architecture: "标准 CRUD"
    components: ["CustomerController", "CustomerService", "CustomerMapper"]

第四步：配置 MCP 服务（可选）

如果需要更强的上下文管理能力：

# 安装 superdesign MCP 服务
git clone https://github.com/jonthebeef/superdesign-mcp-claude-code.git
cd superdesign-mcp-claude-code
npm install && npm run build

# 配置到 Claude Code
claude mcp add superdesign "node /path/to/dist/index.js"

# 验证
claude mcp list

实战工作流

探索式开发

当需求不明确时，让 AI 帮你梳理：

我要开发一个电商系统，帮我分析需要哪些核心模块

AI 会基于上下文基线，结合行业知识给出建议。

明确需求开发

需求清晰时，直接进入实施：

开发客户管理模块，包含：
- 客户 CRUD
- 按姓名/手机号搜索
- 导出 Excel

参考 AIGC/context_base.yaml 的技术栈和代码模式

AI 会按照你定义的模式生成代码。

目录结构建议

项目根目录/
├── AIGC/
│   ├── context_base.yaml      # 项目基线
│   ├── reasoning_baseline.yaml # 推理基线
│   └── requirements/          # 需求文档
│       ├── REQ_001_客户管理.yaml
│       └── REQ_002_订单管理.yaml
├── CLAUDE.md                  # Claude Code 配置
└── src/                       # 源代码

质量保证

推理质量检查清单

  • 需求描述是否使用 EARS 格式？
  • 是否有明确的验收场景？
  • 决策是否记录了推理过程？
  • 技术方案是否考虑了替代方案？

常见问题

AI 生成的代码不符合项目规范？

检查 context_base.yaml 中的 code_patterns 是否完整，补充更多示例代码。

AI 不理解业务术语？

在 domain_knowledge 中添加术语解释和实体关系。

生成的代码质量不稳定？

增加 reasoning_baseline.yaml 中的决策历史，让 AI 理解设计思路。

核心要点

  1. 知识显性化：把项目的隐性知识写成文档
  2. 格式标准化：使用 YAML 等结构化格式，AI 更容易理解
  3. 决策可追溯：记录为什么这样做，而不只是做了什么
  4. 持续迭代：随着项目演进，不断更新上下文文档

上下文工程不是一次性工作，而是持续的知识管理过程。投入越多，AI 的输出质量越高。