WPF 项目 接入 Claude Code实战指南（其它项目也可参考）

摘要

本指南旨在为使用 WPF 的开发者，提供一份全面且实用的 Claude Code 接入实战操作流程。内容涵盖环境概览、工作模式选择、项目配置、Skills 手动配置、MCP 服务器集成、项目管理以及 Bug 修复与代码重构的实战场景，旨在帮助您充分利用 AI 提升开发效率。

1. 您的开发环境概览

您已具备以下高效的开发环境，为 Claude Code 的接入奠定了坚实基础：

• .NET 8 开发环境: 现代 WPF 应用的基石，提供最新的语言特性和框架功能。
• IDE: Visual Studio 2026 或 VS Code，提供强大的代码编辑、调试和项目管理能力。
• Claude Code Desktop: 提供直观的桌面交互界面，是您与 Claude Code 交互的主要平台。
• DeepSeek v4 大模型: 作为 Claude Code 的后端智能引擎，提供卓越的代码理解、生成和优化能力。

2. Claude Code 与 WPF 项目的工作流

下图展示了 Claude Code 如何与您的 WPF 项目及开发环境协同工作，形成一个高效的开发闭环：

工作流说明：

1. 开发者在 Visual Studio / VS Code 中编写和编辑 WPF 项目的 C# 和 XAML 源代码。
2. Claude Code Desktop 会读取项目根目录下的 CLAUDE.md (项目行为准则) 和 .claude/settings.json (权限与自动化配置) 文件，以理解项目上下文和执行规则。
3. 开发者通过 Terminal 或 Claude Code Desktop 的交互界面向 Claude Code Desktop 输入指令（例如 Bug 修复或代码重构请求）。
4. Claude Code Desktop 根据指令，分析 WPF 项目的源代码，并提出修改建议或直接进行代码修改。
5. Claude Code Desktop 将修改建议或直接修改后的代码通过文件系统同步到您的项目源代码中。
6. Visual Studio / VS Code 会检测到代码变更，开发者可以进行代码审查和调试。
7. Claude Code Desktop 还会根据 .claude/settings.json 中配置的 hooks，在代码修改后自动执行 dotnet build 或 dotnet format 等命令，确保代码质量和一致性。

3. 核心选择：Cowork 模式 vs Code 模式

在 Claude Code Desktop 中，选择正确的工作模式对于发挥其最大效能至关重要。下表对比了两种模式的核心差异和适用场景 [1]：

模式	核心定位	适用场景	优势	劣势
Code 模式	深度编码与构建	修改 Bug、重构代码、运行测试、Git 提交、复杂代码分析	直接访问本地文件系统，支持终端命令，Git 感知，Token 效率高，提供最大控制权，可查看每一步操作。	较少安全防护，需手动关注操作，可能执行破坏性命令。
Cowork 模式	任务执行与协作	生成文档、自动化报告、跨应用数据处理、定时任务、非代码类知识工作	运行在隔离的 VM 中，支持生成 Excel/PPT 等真实文档，支持定时任务，提供沙盒环境安全性。	Token 消耗较高，操作透明度较低，无法直接运行终端命令或 Git，不适合深度代码修改。

实战建议：

• 修改 Bug 或重构代码时：请务必使用 Code 模式。它能直接读取您的 XAML 和 C# 文件，运行 dotnet build 验证修复，并直接生成 Git Commit，提供最精细的控制和最高的效率。
• 编写项目文档或技术规格书时：可以使用 Cowork 模式，让它根据代码生成详细的 Markdown 或 Word 文档，或进行数据分析和报告生成。

4. 项目配置：让 Claude Code 懂你

为了让 Claude Code 能够高效地协助您，关键在于为它提供清晰的项目上下文和行为规则。这主要通过配置 CLAUDE.md 和 .claude/settings.json 文件来实现。

4.1 配置 CLAUDE.md (项目行为准则)

在您的 WPF 项目根目录创建 CLAUDE.md 文件。这个文件是 Claude Code 理解您项目架构、编码规范和工作流程的“说明书”。它会在每个会话开始时被 Claude 读取，提供持久化的上下文 [2]。

示例 CLAUDE.md 内容：

# CLAUDE.md - [您的 WPF 项目名称] 指南

## 概述
本 WPF 项目旨在 [项目的一句话描述]。

## 技术栈
- **框架**: .NET 8 / WPF
- **UI 模式**: MVVM Pattern (推荐使用 CommunityToolkit.Mvvm)
- **数据访问**: Entity Framework Core (如果适用)
- **UI 语言**: XAML
- **逻辑语言**: C#

## 项目结构
- `src/Models/`: 定义数据模型和业务实体。
- `src/ViewModels/`: 包含视图的逻辑和命令处理，实现数据绑定。
- `src/Views/`: 包含 XAML 窗口和用户控件的定义。
- `src/Services/`: 包含业务逻辑、API 客户端和数据存储服务。
- `src/Utilities/`: 包含通用的辅助类和扩展方法。

## 常用命令
- **构建项目**: `dotnet build`
- **运行测试**: `dotnet test`
- **运行应用**: `dotnet run --project src/YourProjectName.csproj` (请替换 `YourProjectName.csproj`)
- **格式化代码**: `dotnet format`

## 编码规范
- **MVVM 强制执行**: 严格遵循 MVVM 模式，禁止在 `.xaml.cs` (Code-behind) 文件中编写业务逻辑。所有 UI 交互逻辑应通过 `RelayCommand` 和 `ObservableProperty` 等 MVVM 工具实现。
- **命名约定**: 属性和方法使用 PascalCase，私有字段使用 camelCase 并带有 `_` 前缀。
- **XAML 最佳实践**: 
  - 优先使用 `StaticResource` 或 `DynamicResource` 来定义和应用样式、模板和转换器。
  - 布局管理优先使用 `Grid` 和 `StackPanel`。
  - 使用 `d:DataContext` (设计时数据上下文) 来在 Visual Studio 设计器中预览数据绑定效果。
- **异步编程**: 对于 I/O 操作或耗时任务，始终使用 `Async/Await` 模式，以确保 UI 的响应性。

## 调试指南
- **绑定问题**: 当遇到 XAML 数据绑定失效时，请检查 Visual Studio 的 **Output (输出)** 窗口，其中会显示详细的绑定错误信息。将这些错误信息提供给 Claude Code 进行分析。
- **DataContext 验证**: 确保 XAML 视图的 `DataContext` 已正确设置，无论是通过代码还是 XAML 标记。

## 工作流规则
- **原子性提交**: 每次提交应只包含一个逻辑上的变更。
- **功能分支**: 在进行任何新功能开发或 Bug 修复前，请先创建新的功能分支。
- **测试驱动**: 鼓励为新功能编写单元测试，并确保现有测试通过。

配置要点：

• 精简与聚焦：CLAUDE.md 应保持精简，只包含对 Claude Code 理解项目至关重要的信息。避免冗余，让 AI 能够快速抓住重点。
• 明确技术细节：清晰地说明您使用的 .NET 版本、WPF 库、MVVM 框架（如 CommunityToolkit.Mvvm）等，这将帮助 Claude Code 遵循正确的 API 和最佳实践。

4.2 配置 .claude/settings.json (权限与自动化)

在项目根目录创建一个名为 .claude 的文件夹，并在其中创建 settings.json 文件。这个文件用于定义 Claude Code 的执行权限和自动化钩子 [2]。

示例 settings.json 内容：

{
  "preApprovedCommands": [
    "dotnet build",
    "dotnet test",
    "dotnet format",
    "git status",
    "git add .",
    "git commit -m \"...\""
  ],
  "hooks": {
    "PostToolUse": "dotnet build",
    "OnFileWrite": "dotnet format --include {file}"
  }
}

配置要点：

• preApprovedCommands：将您常用的 dotnet 和 git 命令添加到此列表中，可以减少 Claude Code 在执行这些命令时频繁的确认提示，提高交互效率。
• hooks：
  • PostToolUse: 在 Claude Code 修改代码后自动运行 dotnet build，确保修改后的代码能够编译通过。
  • OnFileWrite: 在 Claude Code 写入文件后自动运行 dotnet format --include {file}，保持代码风格一致。

5. 必备 Skills 与 MCP 服务器配置

5.1 手动配置 Skills (解决中国区搜索限制)

由于网络环境限制，您可能无法直接搜索或安装 Claude Code 的 Skills。但您可以通过在本地创建 SKILL.md 文件来手动赋予 Claude 专家能力 [2]。

配置步骤：

1. 在您的个人配置目录（通常是 ~/.claude/skills/）或项目根目录的 .claude/skills/ 下创建一个文件夹（例如 wpf-expert）。
2. 在该文件夹内创建 SKILL.md 文件。

必备 Skills 模板：WPF/MVVM 专家
将以下内容保存到 ~/.claude/skills/wpf-expert/SKILL.md (推荐放在个人配置目录，以便所有项目共享)：

---
description: 专门用于 WPF 开发、MVVM 模式优化和 XAML 调试的专家技能。当用户要求修改 WPF UI、优化 ViewModel 或修复数据绑定问题时自动加载。
---

# WPF & MVVM 专家指令

## 核心原则
- **MVVM 纯净度**: 严禁在 Code-behind (`.xaml.cs`) 中编写业务逻辑。
- **异步安全**: 耗时操作必须使用 `async/await`，UI 更新必须回到主线程。
- **资源管理**: 优先使用 `StaticResource` 和 `DynamicResource`。

## 常用检查清单
1. 检查 `DataContext` 是否正确绑定。
2. 检查 `Command` 是否使用了 `RelayCommand` 或 `AsyncRelayCommand`。
3. 检查属性更改是否触发了 `OnPropertyChanged`。
4. 检查 XAML 中是否有硬编码的字符串或颜色，建议提取到 `App.xaml` 资源字典。

## 自动化工具
- 运行 `dotnet build` 验证 XAML 编译错误。
- 运行 `dotnet format` 保持 C# 代码风格。

5.2 必备 MCP 服务器详细地址

MCP (Model Context Protocol) 让 Claude 能够连接外部工具和数据源 [2]。以下是 WPF 开发最推荐的三个 MCP 服务器，它们能扩展 Claude 的知识边界和操作能力：

服务器名称	功能描述	安装/配置指令 (Transport: stdio)
Google Search	搜索最新的 .NET 8 API 文档、WPF 社区解决方案、Stack Overflow 答案等。	claude mcp add --transport stdio google-search -- npx -y @modelcontextprotocol/server-google-search
GitHub	管理 Issue、Pull Request (PR) 和代码审查，让 Claude 直接在 GitHub 上进行操作。	claude mcp add --transport stdio github -- npx -y @modelcontextprotocol/server-github
Memory	帮助 Claude 记住您项目特有的架构决策、历史 Bug、解决方案和编码习惯，形成长期记忆。	claude mcp add --transport stdio memory -- npx -y @modelcontextprotocol/server-memory

如何添加 MCP 服务器？

在 Claude Code Desktop 的终端中，直接运行上述表格中对应的 claude mcp add 命令即可。例如，添加 Google Search MCP：

claude mcp add --transport stdio google-search -- npx -y @modelcontextprotocol/server-google-search

注意：某些 MCP 服务器可能需要您设置环境变量（如 API Key）进行认证。您可以使用 --env KEY=VALUE 参数在 claude mcp add 命令中进行配置。具体请参考对应 MCP 服务器的文档。

6. Code 模式：项目管理实战

在 Code 模式下，Claude Code 是以目录为中心工作的，它会读取当前目录及其父目录下的 .claude 配置。

6.1 如何“创建”项目？

Claude Code 不直接提供 create-project 命令，它依赖于 .NET CLI 来初始化项目。您可以通过以下步骤创建新的 WPF 项目并让 Claude Code 介入：

1. 打开终端：在 Claude Code Desktop 中打开一个新的终端会话。
2. 创建项目：使用 .NET CLI 创建一个新的 WPF 项目：

   dotnet new wpf -n MyNewWpfApp
   

   （请将 MyNewWpfApp 替换为您的项目名称）
3. 进入项目目录：

   cd MyNewWpfApp
   

4. 启动 Claude Code：在项目根目录下输入 claude 命令。此时 Claude Code 会自动识别这是一个新项目，并建议您创建 CLAUDE.md 和 .claude/settings.json 文件。

6.2 如何“切换”项目？

Claude Code 始终运行在您启动它的当前目录下。切换项目有以下两种主要方式：

• 方法一（推荐，适用于单个终端会话）：在终端中 cd 到另一个项目目录，然后重新运行 claude 命令。Claude Code 会加载新项目目录的上下文。
• 方法二（多会话，适用于 Claude Code Desktop）：Claude Code Desktop 支持多标签页。您可以点击顶部的 + 号，在新的标签页中选择不同的文件夹打开，从而实现多项目并行工作，每个标签页对应一个项目上下文。

7. 实战场景：Bug 修复与代码重构

一旦 CLAUDE.md、.claude/settings.json 和相关 Skills/MCP 配置完成，您就可以开始利用 Claude Code 协助您的 WPF 项目开发了。

7.1 Bug 修复实战

场景：您的 WPF 应用中，一个用户注册表单的“提交”按钮点击后没有任何反应。

您的指令：

1. 定位问题：首先，您可以在 Visual Studio 中运行应用，尝试点击“提交”按钮，并检查 Visual Studio 的 Output (输出) 窗口是否有 XAML 绑定错误信息。假设您看到了类似 BindingExpression path error: 'SubmitCommand' property not found on 'object' 'YourProject.ViewModels.RegisterViewModel' 的错误 [3]。
2. 向 Claude Code 发出指令：在 Claude Code Desktop 的终端中，输入详细的指令，并附上错误信息：

   “我在用户注册表单的‘提交’按钮上遇到了问题。点击后没有反应，并且 Visual Studio 的输出窗口显示 BindingExpression path error: 'SubmitCommand' property not found on 'object' 'YourProject.ViewModels.RegisterViewModel'. 请检查 RegisterView.xaml 中的 Command 绑定和 RegisterViewModel.cs 中 SubmitCommand 的定义，并修复它。”

Claude Code 的响应：

• Claude Code 会分析 RegisterView.xaml 和 RegisterViewModel.cs，查找 SubmitCommand 的定义和绑定问题。
• 它可能会发现 ViewModel 中命令名称拼写错误，或者 XAML 绑定路径不正确。
• Claude Code 会提出修改建议，例如将 SubmitCommand 更正为 RegisterCommand，或调整 XAML 绑定。
• 在您确认后，它会应用修改，并自动触发 dotnet build 检查编译结果。

7.2 代码重构实战

场景：您的 ProductService.cs 中有一个 LoadProducts 方法，它直接在 UI 线程上执行数据库查询，导致 UI 卡顿。

您的指令：

“请审查 ProductService.cs 中的 LoadProducts 方法。它目前在 UI 线程上执行耗时的数据库操作，导致应用卡顿。请将数据库查询逻辑移动到后台线程执行，并确保结果返回到 UI 线程进行更新，以保持 UI 响应性。请使用 async/await 模式。”

Claude Code 的响应：

• Claude Code 会分析 ProductService.cs 中的 LoadProducts 方法。
• 它会建议将数据库查询封装在 Task.Run 中，并使用 await 关键字等待结果。
• 对于 UI 更新，它会确保通过 Dispatcher.Invoke 或 CommunityToolkit.Mvvm 提供的 MainThread 调度器将数据更新操作返回到 UI 线程。
• 在您确认后，它会重构代码，并自动触发 dotnet format 保持代码风格。

8. 最佳实践建议

• 清晰的指令：与 Claude Code 交互时，指令越具体、越清晰，它给出的解决方案就越准确。提供错误日志、期望行为和相关文件路径是关键。
• 逐步验证：对于复杂的任务，不要一次性让 Claude Code 完成所有工作。分阶段进行，并在每个阶段后进行验证。
• 版本控制：始终在 Git 分支上工作。在让 Claude Code 进行重大修改前，创建一个新分支，并定期提交更改。这使得回滚和审查变得容易。
• 利用桌面版优势：Claude Code Desktop 通常与您的本地文件系统集成更紧密，可以更方便地读取和写入文件。同时，它可能提供更丰富的可视化反馈。
• 利用 Hooks 自动化：在 .claude/settings.json 中配置 PostToolUse 和 OnFileWrite 钩子，让 Claude 在修改代码后自动执行 dotnet build 和 dotnet format，确保代码质量和一致性。

参考文献

[1] Kent Gigger. Chat vs Cowork vs Code: how to pick the right Claude mode. https://kentgigger.com/posts/claude-chat-vs-cowork-vs-code
[2] Claude Code Docs. Extend Claude Code. https://code.claude.com/docs/en/overview
[3] platform.uno. Debugging Silent XAML Binding Failures in 2 Minutes. https://platform.uno/blog/debugging-silent-xaml-binding-failures-in-2-minutes/