shanraisshan / claude-code-best-practice

Problem: 开发者需要Claude处理一个复杂的多步骤任务（如重构整个代码库），但单次提示难以清晰描述所有要求，且Claude容易在长对话中迷失上下文。

Solution: 使用项目的子代理（Subagents）概念，为重构任务创建专门的“重构专家”代理，配置其工具、权限和记忆，让它在独立上下文中专注执行特定子任务。

Example: 创建一个`.claude/agents/refactor-agent.md`，定义该代理专门负责代码重构，拥有访问文件系统、运行测试的权限，并配置其记忆规则，然后通过工作流编排让多个这样的子代理协作完成大型重构。

Problem: 团队中每个成员都在重复编写相似的Claude提示来执行常见任务（如生成API文档、代码审查），导致效率低下且质量参差不齐。

Solution: 利用项目的技能（Skills）和命令（Commands）机制，将团队的最佳实践封装成可复用的知识块和模板，放入项目仓库的`.claude/`目录中，实现自动发现和共享。

Example: 将“生成Swagger风格API文档”的提示模板保存为`.claude/skills/api-doc/SWAGGER_DOC.md`技能，团队成员只需在对话中提及`@api-doc`，Claude就会自动加载并使用这个标准化模板。

Problem: 开发者希望Claude在编码时能实时查询数据库、调用内部API或使用特定开发工具，但Claude本身无法直接访问这些外部资源。

Solution: 通过项目介绍的MCP（Model Context Protocol）服务器配置，将外部工具（数据库、API、内部系统）安全地暴露给Claude，使其能在编码上下文中直接使用这些工具。

Example: 配置一个连接公司内部JIRA的MCP服务器，当Claude编写与特定任务相关的代码时，可以自动查询JIRA获取任务详情、验收标准，确保代码符合需求。

Problem: 在长期项目中，开发者需要Claude记住项目的架构决策、技术债务、特定约定等上下文，但Claude的对话记忆有限且易丢失。

Solution: 使用项目的记忆系统，通过`CLAUDE.md`文件、规则目录（`.claude/rules/`）和项目特定记忆文件夹，为Claude建立持久化的项目上下文记忆。

Example: 在项目根目录创建`CLAUDE.md`记录核心架构，在`.claude/rules/`中放置编码规范文件，Claude在每次会话开始时都会自动加载这些记忆，保持对项目长期背景的理解。