17d - 开发中的上下文工程

文件选择决策树：

任务描述 → 需要修改的文件（必选）
         → 相关类型/接口定义（必选）
         → 设计文档/Spec（推荐）
         → 类似实现的参考文件（可选）
         → 测试文件（如果任务包含测试）
         
❌ 不要加入的：
   - 整个 node_modules 或 vendor 目录
   - 无关模块的实现文件
   - 历史变更日志
   - 构建产物

# 引用单个文件
#File src/sync_engine.rs

# 引用整个目录（Kiro 会智能筛选相关文件）
#Folder src/components/

# Spec 文件自动注入——无需手动引用
# Kiro 的 Spec 工作流会自动将 requirements.md、design.md
# 作为上下文提供给 AI Agent

# 引用文件
@file src/sync_engine.rs

# 引用文件夹
@folder src/components/

# 语义搜索整个代码库（适合不确定文件位置时）
@codebase "文件同步的冲突检测逻辑在哪里？"

# 引用外部文档
@docs https://docs.rs/tokio/latest/tokio/

# 添加文件到当前会话上下文
/add src/sync_engine.rs src/types.rs src/config.rs
 
# 添加整个目录
/add src/components/
 
# 当上下文过大时，压缩历史对话
/compact
 
# 清除上下文重新开始
/clear

┌─────────────────────────────────────────────┐
│ 层级 1：最小上下文（简单修改）               │
│ • 目标文件 + 直接依赖的类型定义              │
│ • 适合：修 bug、改样式、加字段               │
│ • 示例：修改按钮组件 → Button.tsx + types.ts │
├─────────────────────────────────────────────┤
│ 层级 2：模块上下文（功能开发）               │
│ • 目标文件 + 同模块文件 + 接口定义 + Spec    │
│ • 适合：实现新功能、重构模块                 │
│ • 示例：实现同步引擎 → engine.rs + types.rs  │
│         + config.rs + design.md              │
├─────────────────────────────────────────────┤
│ 层级 3：跨模块上下文（架构变更）             │
│ • 多个模块的核心文件 + 架构文档 + 测试       │
│ • 适合：跨模块重构、API 变更                 │
│ • 示例：修改 API 层 → routes/ + services/    │
│         + models/ + tests/ + openapi.yaml    │
└─────────────────────────────────────────────┘

请实现 [任务描述]。

相关上下文：
- 设计文档：参考 design.md 中的 [具体章节]
- 类型定义：见 [types 文件路径]
- 参考实现：[类似模块路径] 中有类似的实现模式
- 编码规范：遵循项目 Steering/Rules 文件中的约定

只修改以下文件：
- [文件1路径]
- [文件2路径]

不要修改其他文件。不要引入新的依赖。

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
      }
    }
  }
}

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost:5432/mydb"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
      }
    }
  }
}

场景 1：全栈 Web 开发
├── GitHub MCP（任务管理 + PR）
├── PostgreSQL MCP（数据库 schema 查询）
├── Context7 MCP（查阅框架文档）
└── Playwright MCP（E2E 测试）

场景 2：前端开发
├── Figma MCP（设计稿读取）
├── Chrome DevTools MCP（实时调试）
├── Context7 MCP（组件库文档）
└── GitHub MCP（issue 追踪）

场景 3：后端 API 开发
├── PostgreSQL MCP（数据库操作）
├── Docker MCP（容器管理）
├── Sentry MCP（错误追踪）
└── GitHub MCP（代码审查）

场景 4：DevOps / 基础设施
├── Docker MCP（容器管理）
├── GitHub MCP（CI/CD 配置）
└── Sentry MCP（监控告警）

⚠️ MCP 安全清单：

1. 永远不要在配置文件中硬编码密钥
   ✅ 使用环境变量：${GITHUB_TOKEN}
   ❌ 直接写入：ghp_abc123...

2. 数据库 MCP 使用只读连接
   ✅ postgresql://readonly_user:pass@host/db
   ❌ postgresql://admin:pass@host/db

3. 限制 MCP Server 的权限范围
   - GitHub MCP：只授予必要的 scope（repo:read）
   - 文件系统 MCP：限制可访问的目录

4. 不要将 .mcp.json 提交到公开仓库
   → 添加到 .gitignore
   → 或使用环境变量引用

我正在开发 [功能描述]，需要了解数据库结构。

请通过 PostgreSQL MCP：
1. 查询 [表名] 的完整 schema（列名、类型、约束）
2. 查看与 [表名] 相关的外键关系
3. 获取 [表名] 的示例数据（LIMIT 5）

基于查询结果，生成对应的 [TypeScript/Rust] 类型定义。

.kiro/
├── steering/
│   ├── coding-standards.md      # 编码规范（always 模式）
│   ├── architecture.md          # 架构约定（always 模式）
│   ├── testing-standards.md     # 测试规范（always 模式）
│   ├── security-rules.md        # 安全规则（always 模式）
│   └── migration-guide.md       # 迁移指南（manual 模式）
├── specs/
│   └── my-feature/
│       ├── requirements.md
│       ├── design.md
│       └── tasks.md
└── settings/
    └── mcp.json

项目根目录/
├── CLAUDE.md                    # 全局规则（自动加载）
├── src/
│   ├── CLAUDE.md                # 前端特定规则（进入 src/ 时加载）
│   └── components/
│       └── CLAUDE.md            # 组件开发规则（进入 components/ 时加载）
├── server/
│   └── CLAUDE.md                # 后端特定规则
└── tests/
    └── CLAUDE.md                # 测试特定规则

.cursor/
└── rules/
    ├── general.mdc              # 通用规则（always 模式）
    ├── react-components.mdc     # React 组件规则（auto 模式，匹配 *.tsx）
    ├── api-routes.mdc           # API 路由规则（auto 模式，匹配 routes/*.ts）
    └── database.mdc             # 数据库规则（agent 模式，按需加载）

<!-- .kiro/steering/coding-standards.md -->
---
inclusion: always
---
 
# RustSync 编码规范
 
## Rust 代码规范
- 错误处理使用 `thiserror` 定义错误类型，禁止在生产代码中使用 `unwrap()` 或 `expect()`
- 所有公共函数和结构体必须有 `///` 文档注释
- 异步运行时统一使用 `tokio`，不混用其他异步运行时
- 使用 `clippy` 的所有默认 lint，CI 中 `clippy -- -D warnings`
- 文件操作使用 `tokio::fs`，不使用 `std::fs` 的同步版本
 
## TypeScript 代码规范
- 样式使用 CSS Modules（`*.module.css`），不用内联样式或 Tailwind
- 组件使用函数式组件 + hooks，不使用 class 组件
- 类型定义集中在 `src/types/index.ts`，组件 props 类型与组件同文件
- 状态管理使用 React hooks（useState/useReducer），不引入 Redux
 
## 通用规范
- 提交信息使用 Conventional Commits 格式
- 每个模块必须有对应的单元测试文件（`*.test.ts` 或 `*_test.rs`）
- 不引入未在 design.md 中规划的新依赖

# CLAUDE.md
 
## 项目概述
RustSync 是一个基于 Tauri 的文件同步工具，前端 React + TypeScript，后端 Rust。
 
## 关键约定
- Tauri 命令定义在 src-tauri/src/commands.rs
- 前端 API 调用封装在 src/api/ 目录
- 所有 Tauri 命令必须返回 Result<T, String> 类型
 
## 不要做的事
- 不要修改 Cargo.toml 添加新依赖（除非任务明确要求）
- 不要使用 `console.log` 调试，使用项目的 logging 模块
- 不要在组件中直接调用 Tauri invoke，通过 api/ 层封装
 
## 测试
- Rust 测试：cargo test
- 前端测试：npm run test
- 类型检查：npm run typecheck

加载策略决策树：

这条规则每次编码都需要吗？
├── 是 → always 模式（编码规范、架构约定、安全规则）
└── 否 → 这条规则能通过文件路径自动判断吗？
    ├── 是 → auto 模式（前端规则匹配 *.tsx，后端规则匹配 *.rs）
    └── 否 → 这条规则需要 AI 自己判断何时使用吗？
        ├── 是 → agent 模式（数据库迁移指南、性能优化建议）
        └── 否 → manual 模式（一次性迁移指南、特殊场景处理）

<!-- always 模式：每次对话都注入 -->
---
inclusion: always
---
# 编码规范
...
 
<!-- manual 模式：只在用户通过 @steering 显式引用时加载 -->
---
inclusion: manual
---
# 数据库迁移指南
...

<!-- always 模式 -->
---
alwaysApply: true
---
# 通用编码规范
 
<!-- auto 模式：匹配特定文件时自动加载 -->
---
globs: ["src/components/**/*.tsx", "src/components/**/*.css"]
---
# React 组件开发规范
 
<!-- agent 模式：AI 自行判断是否需要 -->
---
alwaysApply: false
---
# 数据库查询优化指南

请审查当前项目的 Steering/Rules 文件，检查以下问题：

1. 是否有冗余或矛盾的规则？
2. 是否有规则过于模糊，AI 难以执行？
3. 是否有重要的项目约定没有被规则覆盖？
4. always 模式的规则是否过多（建议不超过 [N] 个文件）？

输出改进建议，包括：
- 需要删除的冗余规则
- 需要细化的模糊规则
- 需要补充的缺失规则
- 需要调整加载模式的规则

Claude Code：
- 使用 /cost 命令查看当前会话的 token 消耗
- 使用 /compact 在上下文过大时压缩历史对话
- 观察 "Context window usage" 指示器

Cursor：
- 查看聊天窗口底部的 token 计数
- 使用 "New Chat" 开始新会话释放上下文

Kiro：
- 关注 Spec 文件的大小——过大的 design.md 会占用大量上下文
- 使用 #File 精确引用而非 #Folder 批量引用

技术 1：会话分段
├── 每完成一个微任务，开始新的会话
├── 在新会话中只加载下一个任务需要的上下文
└── 避免一个会话跨越多个不相关的任务

技术 2：渐进式上下文加载
├── 先给 AI 最小上下文，让它开始工作
├── 当 AI 需要更多信息时，按需添加
└── 比一次性加载所有文件更高效

技术 3：上下文摘要
├── 对于大型设计文档，提供摘要而非全文
├── 对于长对话历史，使用 /compact 压缩
└── 对于大型代码文件，只引用相关函数而非整个文件

技术 4：四文件工作记忆系统
├── progress.md：当前任务进度和已完成的工作
├── decisions.md：关键技术决策和原因
├── context.md：项目上下文摘要
└── next-steps.md：下一步计划
→ 每次新会话加载这四个文件，恢复工作状态

交叉引用策略：

1. 任务级引用（推荐）
   "请实现 Task 3.2。参考 design.md 中'差异计算引擎'章节的算法设计。"
   → AI 只需要关注设计文档的特定部分

2. 类型级引用
   "请参考 design.md 中的数据模型定义，实现对应的 Rust 结构体。"
   → 聚焦数据模型，忽略其他设计细节

3. 接口级引用
   "请参考 design.md 中的 API 设计，实现 /sync/status 端点。"
   → 只关注 API 接口定义

❌ 避免：
   "请阅读整个 design.md 然后实现这个功能。"
   → 浪费上下文空间，AI 可能被无关信息干扰

当前会话的上下文已经比较大了。请帮我：

1. 总结到目前为止我们完成的工作（3-5 句话）
2. 列出当前正在进行的任务和关键决策
3. 列出下一步需要做的事情

我会用这个摘要开始一个新的会话，以释放上下文空间。

┌─────────────────────────────────────────────────────────┐
│              开发中的上下文工程协同模型                    │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────┐                                       │
│  │ Steering 规则 │ ← 始终注入，设定行为基线              │
│  │ (编码规范、   │                                       │
│  │  架构约定)    │                                       │
│  └──────┬───────┘                                       │
│         ↓                                               │
│  ┌──────────────┐                                       │
│  │ Spec 文件     │ ← 任务级注入，提供需求和设计上下文     │
│  │ (requirements │                                       │
│  │  + design)    │                                       │
│  └──────┬───────┘                                       │
│         ↓                                               │
│  ┌──────────────┐                                       │
│  │ 精选代码文件  │ ← 按需引用，提供实现上下文             │
│  │ (目标文件 +   │                                       │
│  │  类型 + 参考) │                                       │
│  └──────┬───────┘                                       │
│         ↓                                               │
│  ┌──────────────┐                                       │
│  │ MCP 工具      │ ← 按需调用，获取外部信息              │
│  │ (DB schema,   │                                       │
│  │  GitHub, docs)│                                       │
│  └──────────────┘                                       │
│                                                         │
│  → AI Agent 在这个精心策划的上下文中执行任务 →            │
│                                                         │
└─────────────────────────────────────────────────────────┘

完整的上下文工程工作流（每个微任务）：

1. 开始新会话（或 /compact 压缩旧会话）
2. Steering 规则自动加载 ← 无需手动操作
3. 引用当前任务的 Spec 上下文
   - Kiro：自动注入
   - Claude Code："参考 SPEC.md 中的 Task 3.2"
4. 精确引用需要的代码文件
   - 目标文件 + 类型定义 + 参考实现
5. 如需外部信息，通过 MCP 获取
   - "查询 users 表的 schema"
   - "查看 GitHub issue #42 的描述"
6. 执行任务
7. 审查输出，确认符合 Steering 规则
8. 完成后更新工作记忆文件（progress.md）

rustsync/
├── .kiro/
│   ├── steering/
│   │   ├── coding-standards.md     # 编码规范（always）
│   │   ├── rust-patterns.md        # Rust 特定模式（always）
│   │   └── testing-guide.md        # 测试指南（always）
│   ├── specs/
│   │   └── rustsync-tool/
│   │       ├── requirements.md     # 12 个用户故事
│   │       ├── design.md           # 架构设计
│   │       └── tasks.md            # 25 个实现任务
│   └── settings/
│       └── mcp.json                # MCP 配置
├── src-tauri/src/                   # Rust 后端
│   ├── sync_engine.rs
│   ├── diff.rs
│   ├── config.rs
│   └── ...
├── src/                             # React 前端
│   ├── components/
│   ├── hooks/
│   ├── api/
│   └── types/index.ts
└── .gitignore                       # 包含 .kiro/settings/mcp.json

<!-- .kiro/steering/coding-standards.md -->
---
inclusion: always
---
 
# RustSync 编码规范
 
## Rust 代码
- 使用 `thiserror` 处理错误，不要用 `unwrap()`
- 所有公共函数必须有文档注释（`///`）
- 使用 `clippy` 的所有默认 lint
- 异步代码使用 `tokio`
- Tauri 命令返回 `Result<T, String>`
 
## TypeScript 代码
- 使用 CSS Modules，不用内联样式
- 组件使用函数式组件 + hooks
- 类型定义集中在 types/index.ts
- API 调用封装在 api/ 目录
 
## 测试
- 每个模块必须有单元测试
- 核心逻辑必须有 Property-Based Testing
- 测试文件与源文件同目录

// .kiro/settings/mcp.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Task: 实现文件差异计算模块（diff.rs）

上下文选择：
├── Steering：coding-standards.md（自动加载）
├── Spec：design.md 中"差异计算引擎"章节
├── 代码文件：
│   ├── src-tauri/src/diff.rs（目标文件）
│   ├── src-tauri/src/types.rs（类型定义）
│   ├── src-tauri/src/sync_engine.rs（调用方，了解接口需求）
│   └── src-tauri/src/config.rs（配置项）
├── MCP：无需外部工具
└── 总上下文估算：~15K tokens（远低于 200K 限制）

提示词：
"请实现 Task 4：文件差异计算模块。
 参考 design.md 中差异算法的设计。
 diff.rs 需要实现 compute_diff() 函数，
 接受两个文件路径，返回 DiffResult。
 类型定义见 types.rs。
 遵循 Steering 中的 Rust 编码规范。"