{"id":32784714,"url":"https://github.com/optima-chat/cc-best-practice","last_synced_at":"2025-11-05T02:02:09.007Z","repository":{"id":322087683,"uuid":"1088167113","full_name":"Optima-Chat/cc-best-practice","owner":"Optima-Chat","description":"Claude Code 使用技巧和最佳实践的中文社区集合","archived":false,"fork":false,"pushed_at":"2025-11-02T14:49:27.000Z","size":108,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-02T15:06:46.775Z","etag":null,"topics":["awesome","best-practices","chinese","claude-code","development","tutorial"],"latest_commit_sha":null,"homepage":"https://www.cc-chat.dev","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Optima-Chat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-02T12:59:39.000Z","updated_at":"2025-11-02T14:49:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Optima-Chat/cc-best-practice","commit_stats":null,"previous_names":["optima-chat/cc-best-practice"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Optima-Chat/cc-best-practice","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Optima-Chat%2Fcc-best-practice","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Optima-Chat%2Fcc-best-practice/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Optima-Chat%2Fcc-best-practice/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Optima-Chat%2Fcc-best-practice/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Optima-Chat","download_url":"https://codeload.github.com/Optima-Chat/cc-best-practice/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Optima-Chat%2Fcc-best-practice/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":282745088,"owners_count":26720200,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-05T02:00:05.946Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["awesome","best-practices","chinese","claude-code","development","tutorial"],"created_at":"2025-11-05T02:00:51.615Z","updated_at":"2025-11-05T02:02:08.994Z","avatar_url":"https://github.com/Optima-Chat.png","language":null,"readme":"# Claude Code 最佳实践\n\n[![GitHub stars](https://img.shields.io/github/stars/Optima-Chat/cc-best-practice?style=social)](https://github.com/Optima-Chat/cc-best-practice/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/Optima-Chat/cc-best-practice?style=social)](https://github.com/Optima-Chat/cc-best-practice/network/members)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)\n\n\u003e 先想清楚，再动手\n\n## 目录\n\n- [核心原则](#核心原则)\n- [如何讨论技术方案](#如何讨论技术方案)\n- [行业最佳实践](#行业最佳实践)\n- [保存技术方案](#保存技术方案)\n- [案例对比](#案例对比)\n- [开发流程](#开发流程)\n- [可视化](#可视化)\n- [测试驱动开发](#测试驱动开发)\n- [社区](#社区)\n\n## 核心原则\n\n先讨论技术方案，理解所有细节，确认无误后再写代码。讨论方案 1-2 小时，写代码 10-20 分钟。方案没想清楚就动手，返工时间可能是几小时甚至几天。\n\n**黄金法则：讨论方案的时间能省下十倍的返工时间**。\n\n## 如何讨论技术方案\n\n告诉 Claude Code：\"我想实现某功能，先讨论技术方案，不要写代码。\" 然后提问：整体架构是什么？需要哪些模块？数据流如何？技术选型？可能的坑？\n\n对任何不理解的地方都要问清楚。为什么用 Redis 而非 Memcached？中间件执行顺序为何这样安排？WebSocket 和轮询的区别？数据结构为何这样设计？必须完全理解每个决策。\n\n**核心：充分理解技术方案，实施遇到问题时才能给出有效判断**。\n\n## 行业最佳实践\n\n让 Claude Code 提供多个方案和行业最佳实践对比，选择最合适的：\n\n**询问行业经验：**\n```\n\"这个场景的行业最佳实践是什么？\"\n\"业界通常如何解决这类问题？\"\n\"大厂是怎么做的？\"\n```\n\nClaude Code 训练数据包含大量开源项目和技术文档，能提供有价值的行业经验参考。\n\n**多方案对比：**\n```\n\"给出三种方案：\n1. 最简单快速能上线的\n2. 性能最优的\n3. 最灵活可扩展的\n\n分析每个方案的优缺点、适用场景、实施成本。\"\n```\n\n权衡利弊后选择最合适的方案，把选型理由和被否决方案的原因都记录到 docs。\n\n**核心：多方案对比，基于业界经验决策，避免闭门造车**。\n\n## 保存技术方案\n\n讨论完的技术方案必须记录下来。在项目根目录建 `docs` 文件夹，保存技术方案、架构设计、技术决策。告诉 Claude Code：\"把我们讨论的方案整理成文档，保存到 @docs 目录。\"\n\n原因：Claude Code 无法跨 session 保持上下文。复杂项目需要多个 session 完成，每次新 session 都需要重新理解技术方案。有文档，直接 @docs 让它读取；没文档，每次都要重新讨论，浪费时间。讨论过程中的架构图、数据流图、时序图都要保存，图比文字更直观。\n\n**核心：docs 是跨 session 的上下文，没有文档就没有记忆**。\n\n## 案例对比\n\n### 购物车功能\n\n**常规做法：**\n\"帮我实现购物车功能\" → 写代码 → \"要支持多规格\" → 改代码 → \"数据要存服务端\" → 大改 → \"要支持优惠券\" → 继续改。\n\n问题：需求不断变化，架构不断调整，代码越来越混乱。可能最后发现整体方案不合理，需要推倒重来。\n\n**推荐做法：**\n\"实现购物车功能，需求：多规格商品、服务端存储、优惠券、库存检查、游客和登录用户。请给技术方案。\" → 讨论方案，理解所有细节 → \"保存方案到 docs，开始实现\" → 一次到位，架构清晰。\n\n### API 性能优化\n\n**常规做法：**\n\"API 很慢，帮我优化\" → 加缓存、加索引 → 效果不明显 → 继续尝试 → 方向不对，优化失败。\n\n**推荐做法：**\n\"API 响应慢，分析原因：数据库、网络还是计算？列出优化方案，评估收益成本，给出优先级。\" → 发现 N+1 查询问题 → 问清楚什么是 N+1 → 讨论 JOIN 方案 → 确定方案：JOIN + Redis → 保存到 docs → 实现 → 问题解决。\n\n**核心：需求越完整，实现越高效**。\n\n## 开发流程\n\n标准 GitHub 工作流，Claude Code 通过 `gh` 命令协助：\n\n1. 创建 issue 描述需求，用 `gh issue create` 或让 CC 创建\n2. 创建功能分支，讨论技术方案并保存到 docs\n3. 实现代码，运行测试修复失败用例\n4. 创建 PR 关联 issue（Closes #123），CC 自动生成 PR 描述\n5. Code Review 通过后合并，删除分支\n\n**核心：小步快跑，持续集成**。\n\n**时序图示例（完整功能开发流程）：**\n```mermaid\nsequenceDiagram\n    participant Dev as 开发者\n    participant CC as Claude Code\n    participant GH as GitHub\n    participant Docs as docs/\n    participant Code as 代码库\n\n    Dev-\u003e\u003eCC: 创建 issue 描述新功能需求\n    CC-\u003e\u003eGH: gh issue create\n    GH--\u003e\u003eCC: issue #123 已创建\n\n    Dev-\u003e\u003eCC: 创建分支 feature/new-feature\n    CC-\u003e\u003eCode: git checkout -b feature/new-feature\n\n    Dev-\u003e\u003eCC: 读取 issue #123，讨论技术方案\n    CC-\u003e\u003eGH: gh issue view #123\n    CC-\u003e\u003eDev: 提供技术方案（架构、模块、数据流）\n    Dev-\u003e\u003eCC: 为什么这样设计？行业最佳实践？\n    CC-\u003e\u003eDev: 详细解释和业界参考\n\n    Dev-\u003e\u003eCC: 方案确认，保存到 @docs\n    CC-\u003e\u003eDocs: 保存技术方案文档和架构图\n    Docs--\u003e\u003eCC: 文档已保存\n\n    Dev-\u003e\u003eCC: 开始实现\n    CC-\u003e\u003eDocs: 读取技术方案\n    CC-\u003e\u003eCode: 实现代码\n    Code--\u003e\u003eCC: 代码完成\n\n    Dev-\u003e\u003eCC: 运行测试\n    CC-\u003e\u003eCode: 执行测试套件\n    Code--\u003e\u003eCC: 测试通过\n\n    Dev-\u003e\u003eCC: 创建 PR，关联 issue #123\n    CC-\u003e\u003eCode: git push origin feature/new-feature\n    CC-\u003e\u003eGH: gh pr create --body \"Closes #123\"\n    GH--\u003e\u003eCC: PR #124 已创建\n\n    Note over GH: Code Review\n    GH--\u003e\u003eDev: Review 通过\n\n    Dev-\u003e\u003eCC: 合并 PR\n    CC-\u003e\u003eGH: gh pr merge #124\n    GH-\u003e\u003eCode: 合并到 main 分支\n    GH-\u003e\u003eGH: 自动关闭 issue #123\n    GH--\u003e\u003eCC: PR 已合并，issue 已关闭\n```\n\n## 可视化\n\n**画图：** 要求 Claude Code 用 Mermaid 画架构图、数据流图、时序图、ER 图。Mermaid 语法简单，渲染效果清晰美观，易于理解和维护。GitHub 和大多数 Markdown 编辑器原生支持。把图保存到 docs 目录作为技术文档。\n\n示例请求：\n```\n\"用 Mermaid 画出系统架构图，展示各模块间的调用关系\"\n\"画一个用户登录的时序图，展示前端、后端、数据库的交互流程\"\n```\n\n架构图示例（为 Claude Code 添加 /magic 命令）：\n```mermaid\ngraph TB\n    subgraph CLI[\"CLI 层\"]\n        Parser[命令解析器]\n        Router[命令路由]\n    end\n\n    subgraph Commands[\"命令层\"]\n        Magic[MagicCommand]\n        Other[其他命令...]\n    end\n\n    subgraph Core[\"核心服务层\"]\n        LLM[LLM 服务]\n        Context[上下文管理]\n        FileOps[文件操作]\n    end\n\n    subgraph Storage[\"存储层\"]\n        Config[配置文件]\n        Cache[缓存]\n        Docs[文档]\n    end\n\n    Router -.依赖.-\u003e Magic\n    Router -.依赖.-\u003e Other\n    Magic -.依赖.-\u003e LLM\n    Magic -.依赖.-\u003e Context\n    Context -.依赖.-\u003e FileOps\n    Context -.依赖.-\u003e Cache\n    Context -.依赖.-\u003e Docs\n    Magic -.依赖.-\u003e Config\n\n    style Magic fill:#f9f,stroke:#333,stroke-width:2px\n    style LLM fill:#bbf,stroke:#333,stroke-width:2px\n```\n\n**核心：一图胜千言**。\n\n## 测试驱动开发\n\n充分的测试是代码质量的保障。让 Claude Code 帮你编写和执行测试：\n\n**测试覆盖：**\n- 单元测试：独立函数和模块\n- 集成测试：模块间协作\n- 接口测试：API 端点\n\n**自动化：**\n```\n\"创建测试脚本，集成到 CI/CD\"\n\"配置 GitHub Actions，测试失败禁止合并\"\n```\n\n**核心：测试覆盖越全面，代码质量越有保障**。\n\n---\n\n## 社区\n\n- [CC Chat 社区](https://github.com/optima-chat/cc-chat) - Claude Code 中文社区\n- [GitHub Discussions](../../discussions) - 讨论交流\n\n## 许可证\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foptima-chat%2Fcc-best-practice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foptima-chat%2Fcc-best-practice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foptima-chat%2Fcc-best-practice/lists"}