Claude Code 上下文窗口管理：从治理方法到工程实践

1
# 项目 AI 协作规则
2

3
## 项目背景
4
本项目是一个 Java Web Agent 调度基座，用于支持 Agent 装配、Skill 管理、MCP Client Gateway、意图识别、计划编排和工具调用。
5

6
## 技术栈
7
- Java 17
8
- Spring Boot 3
9
- MySQL
10
- Redis
11
- Spring AI / Spring AI Alibaba Graph
12
- MCP Client Gateway
13
- SSE
14

15
## 代码分层规则
16
- Controller 只负责参数接收、鉴权入口和响应包装。
17
- Service 负责业务逻辑。
18
- Manager / Orchestrator 负责复杂流程编排。
19
- Repository / Mapper 只负责数据访问。
20
- Client / Gateway 负责外部系统连接。
21
- DTO / Request / Response 不混入业务逻辑。
22

23
## 开发规则
24
- 新增模块前，先说明接口设计、文件清单和影响范围。
25
- 每次只实现一个小阶段，避免跨模块大改。
26
- 修改前先读取相关文件，不要全项目扫描。
27
- 不要主动重构无关模块。
28
- 不要删除已有代码，除非用户明确要求。
29
- 不要引入未说明用途的新依赖。
30

31
## 测试与验证
32
- 修改核心逻辑后，需要给出测试方式。
33
- 如果项目已有测试命令，优先运行已有测试。
34
- 如果无法运行测试，需要说明原因和人工验证步骤。
35

36
## 上下文治理规则
37
- 当前任务细节写入 `docs/ai/current-task.md`。
38
- 阶段进度写入 `docs/ai/progress.md`。
39
- 架构决策写入 `docs/ai/decisions.md`。
40
- 跨窗口交接写入 `docs/ai/handoff-summary.md`。
41
- 大范围代码搜索优先交给 subagent，只把摘要带回主上下文。
42
- 切换无关任务时使用 `/clear`。
43
- 长任务继续时先更新 handoff，再使用 `/compact`。

1
# 当前任务：MCP Client Gateway MVP
2

3
## 任务背景
4
当前完整 Agent 调度模块尚未完成，但需要先建设 MCP Client 能力，为后续 Agent 调用外部工具打基础。
5

6
## 本轮目标
7
实现一个最小可用 MCP Client Gateway，用于连接外部 MCP Server、发现工具、注册工具元数据，并通过统一接口调用工具。
8

9
## 本轮要做
10
- MCP Server 配置结构
11
- MCP Client 初始化管理
12
- Tool 发现与注册
13
- Tool 调用服务
14
- HTTP 调用入口
15
- 基础异常处理
16

17
## 本轮不做
18
- 不做 MCP Server 自研
19
- 不做完整 Agent Planner
20
- 不做 Skill 装配工厂
21
- 不做前端页面
22
- 不做多租户权限
23
- 不做复杂可视化
24

25
## 重点目录
26
- `src/main/java/.../mcp/`
27
- `src/main/resources/application.yml`
28
- `docs/mcp-client-gateway-design.md`
29

30
## 完成标准
31
- 可以配置一个外部 MCP Server
32
- 启动后可以加载配置
33
- 可以发现工具列表
34
- 可以通过 HTTP 接口调用某个工具
35
- 调用失败时有明确错误返回

1
请先阅读：
2
1. CLAUDE.md
3
2. docs/ai/current-task.md
4
3. docs/ai/decisions.md
5
4. docs/ai/progress.md
6

7
然后只围绕 current-task.md 中的任务工作。
8
不要主动读取全项目文件。
9
修改代码前先说明准备修改哪些文件。

1
# 开发进度记录
2

3
## 2026-05-21：MCP Client Gateway 阶段 1
4

5
### 已完成
6
- 新增 MCP Server 配置结构。
7
- 新增配置绑定类。
8
- 在 application.yml 中增加 MCP Server 配置样例。
9

10
### 修改文件
11
- `McpServerProperties.java`：读取 MCP Server 配置。
12
- `McpServerConfig.java`：描述单个 MCP Server。
13
- `application.yml`：增加配置样例。
14

15
### 当前未完成
16
- MCP Client 初始化。
17
- Tool 发现。
18
- Tool 调用。
19
- HTTP 调用入口。
20

21
### 下一步
22
- 实现 `McpClientManager`。
23
- 设计 `McpToolRegistry`。
24
- 定义标准调用请求和响应。

1
请更新 docs/ai/progress.md，记录本阶段完成内容、修改文件、未完成事项和下一步。

1
# 架构决策记录
2

3
## ADR-001：第一阶段只做 MCP Client Gateway
4

5
### 背景
6
完整 Agent 模块尚未搭建完成，但项目需要先具备 MCP Client 能力。
7

8
### 决策
9
第一阶段只实现 MCP Client Gateway，不实现 MCP Server，不实现完整 Agent Planner。
10

11
### 原因
12
- 先沉淀工具连接、工具发现、工具调用能力。
13
- 后续 Agent 调度层可以复用该 Gateway。
14
- 避免 Agent、Skill、MCP Server 同时开发导致边界混乱。
15

16
### 影响
17
- 当前模块只关注外部 MCP Server 的连接与调用。
18
- Skill 装配与 Plan-and-Execute 放到后续阶段。
19
- 当前不设计多租户权限和前端管理页面。
20

21
### 状态
22
已采纳。

1
为什么有这个问题？
2
我们选择了什么？
3
为什么这么选？
4
这个选择会影响什么？

1
# 任务交接摘要
2

3
## 当前任务
4
实现 MCP Client Gateway MVP，用于连接外部 MCP Server、发现工具并提供统一调用入口。
5

6
## 已完成内容
7
- 完成 MCP Server 配置结构。
8
- 完成 McpClientManager 初版。
9
- 完成 McpToolRegistry 工具注册逻辑。
10
- 完成 McpToolInvocationService 调用入口。
11
- 完成 McpGatewayController HTTP 接口。
12

13
## 修改过的文件
14
- `McpServerProperties.java`：读取配置。
15
- `McpClientManager.java`：管理 MCP Client。
16
- `McpToolRegistry.java`：缓存工具元数据。
17
- `McpToolInvocationService.java`：统一调用工具。
18
- `McpGatewayController.java`：提供 HTTP API。
19

20
## 关键设计决策
21
- 第一阶段只做 MCP Client，不做 MCP Server。
22
- 工具调用统一走 McpToolInvocationService。
23
- Controller 不直接操作 MCP Client。
24
- Tool 元数据先缓存在内存，暂不落库。
25

26
## 未解决问题
27
- 需要补充工具调用超时控制。
28
- 需要补充调用日志。
29
- 需要考虑多 MCP Server 名称冲突问题。
30
- 需要补充基础测试用例。
31

32
## 下一步建议
33
1. 增加调用超时配置。
34
2. 增加标准错误码。
35
3. 编写基础测试用例。
36

37
## 注意事项
38
- 不要重构 Agent Planner。
39
- 不要新增 Skill 装配逻辑。
40
- 不要把 MCP Server 开发混进当前任务。

1
请先更新 docs/ai/handoff-summary.md，保留：
2
1. 当前任务
3
2. 已完成内容
4
3. 修改过的文件
5
4. 关键设计决策
6
5. 未解决问题
7
6. 下一步建议
8
7. 不要重复做的事项
9

10
更新完成后，我再执行 /compact。

1
/compact

1
上午做 MCP Gateway，下午改论文，晚上问 Git 分支。

1
/compact focus on MCP Client Gateway current status, modified files, design decisions, unresolved issues, and next steps.

1
/context

1
请使用 subagent 调研 MCP 模块相关代码。
2

3
要求：
4
1. subagent 可以读取相关文件和日志。
5
2. 主上下文只返回摘要，不要返回源码全文。
6
3. 摘要包括：
7
   - 相关文件列表
8
   - 每个文件职责
9
   - 当前实现缺口
10
   - 推荐修改点
11
   - 风险点
12
4. 不要修改代码。

1
---
2
name: code-researcher
3
description: Read-only codebase research agent. Use it for large-scale search, file mapping, dependency tracing, and implementation gap analysis.
4
tools: Read, Grep, Glob
5
---
6

7
You are a read-only codebase research agent.
8

9
Your job:
10
1. Locate files relevant to the user's task.
11
2. Summarize responsibilities of each file.
12
3. Identify implementation gaps.
13
4. Return only concise summaries, not full source code.
14
5. Never modify files.
15
6. Prefer file paths, symbols, and line-level findings.

1
---
2
description: Update AI context governance files for the current task.
3
allowed-tools: Read, Edit, Grep, Glob
4
---
5

6
请执行一次上下文维护：
7

8
1. 阅读：
9
   - CLAUDE.md
10
   - docs/ai/current-task.md
11
   - docs/ai/progress.md
12
   - docs/ai/decisions.md
13
   - docs/ai/handoff-summary.md
14

15
2. 检查：
16
   - current-task.md 是否仍然符合当前任务
17
   - progress.md 是否记录了最新阶段
18
   - decisions.md 是否有新架构决策需要补充
19
   - handoff-summary.md 是否可以支持新窗口继续
20

21
3. 更新：
22
   - progress.md
23
   - decisions.md
24
   - handoff-summary.md
25

26
4. 输出：
27
   - 当前状态
28
   - 下一步建议
29
   - 建议是否 /compact 或 /clear

1
/context-sync

1
---
2
description: Start a new task with controlled context.
3
allowed-tools: Read, Grep, Glob
4
argument-hint: [task name]
5
---
6

7
请启动一个受控任务：$ARGUMENTS
8

9
步骤：
10
1. 阅读 CLAUDE.md。
11
2. 阅读 docs/ai/current-task.md。
12
3. 阅读 docs/ai/decisions.md。
13
4. 阅读 docs/ai/progress.md。
14
5. 给出：
15
   - 你理解的任务目标
16
   - 本轮要做什么
17
   - 本轮不做什么
18
   - 需要读取哪些文件
19
   - 计划修改哪些文件
20
6. 在用户确认前不要修改代码。

1
---
2
description: Create or update handoff summary before compacting or switching sessions.
3
allowed-tools: Read, Edit, Grep, Glob
4
---
5

6
请更新 docs/ai/handoff-summary.md，必须包括：
7

8
1. 当前任务
9
2. 已完成内容
10
3. 修改过的文件
11
4. 关键设计决策
12
5. 未解决问题
13
6. 下一步建议
14
7. 不要重复做的事项
15
8. 可以安全忽略的旧信息
16

17
输出完成后，建议用户是否执行 /compact。

1
{
2
  "hooks": {
3
    "PreCompact": [
4
      {
5
        "matcher": "",
6
        "hooks": [
7
          {
8
            "type": "command",
9
            "command": "echo 'Before compact: please update docs/ai/handoff-summary.md'"
10
          }
11
        ]
12
      }
13
    ]
14
  }
15
}

1
帮我实现 MCP Client Gateway。

1
/clear

1
# 当前任务：MCP Client Gateway MVP
2

3
## 本轮目标
4
实现 MCP Client Gateway 的最小可用版本。
5

6
## 本轮要做
7
- MCP Server 配置加载
8
- MCP Client 初始化
9
- Tool 发现
10
- Tool 调用
11
- HTTP 调用入口
12

13
## 本轮不做
14
- 不做 MCP Server
15
- 不做 Agent Planner
16
- 不做 Skill 装配工厂
17
- 不做前端页面

1
请先阅读：
2
1. CLAUDE.md
3
2. docs/ai/current-task.md
4
3. docs/ai/decisions.md
5
4. docs/ai/progress.md
6

7
然后只围绕 current-task.md 工作。
8
先给出任务理解、涉及文件和执行计划，不要立刻改代码。

1
可以。先只完成配置结构和核心接口。
2
每次只实现一个小阶段，完成后更新 progress.md。

1
请更新 docs/ai/progress.md 和 docs/ai/decisions.md。

1
请使用 code-researcher subagent 调查 MCP 调用失败原因。
2
主上下文只返回摘要，不要返回源码全文。

1
/handoff

1
/compact focus on MCP Client Gateway current status, modified files, key decisions, unresolved issues, and next steps.

1
请阅读：
2
1. CLAUDE.md
3
2. docs/ai/handoff-summary.md
4
3. docs/ai/progress.md
5
4. docs/ai/current-task.md
6

7
然后继续 MCP Client Gateway 任务。
8
不要重复已经完成的内容。
9
先给出当前状态理解和下一步计划。

1
/clear
2
/task-start MCP Client Gateway

1
请阅读 CLAUDE.md、docs/ai/current-task.md、docs/ai/progress.md、docs/ai/decisions.md。
2
先给出当前任务理解和计划，不要改代码。

1
每次只完成一个小阶段。
2
修改前说明文件清单。
3
修改后说明变更点和验证方式。
4
阶段结束更新 progress.md。

1
请使用 subagent 调研相关文件。
2
主上下文只返回摘要，不要返回源码全文。

1
/context-sync
2
/handoff

1
/compact

1
/clear

1
Skill Card      轻量检索
2
Skill Manifest  参数和权限
3
Skill Body      详细执行逻辑

1
Profile Memory      用户偏好
2
Project Memory      项目规则
3
Task Memory         当前任务状态
4
Decision Memory     架构决策
5
Tool Memory         工具调用摘要
6
Error Memory        已解决错误和修复方式

1
模块完成
2
测试通过
3
bug 修复
4
任务切换
5
工具结果过大
6
subagent 返回后
7
多轮失败后

1
score = relevance + freshness + authority + reusability - verbosity - staleness