vibe-coding-cn/research/shanraisshan-claude-code-best-practice/deep-dive.md

shanraisshan/claude-code-best-practice 深度研究

研究级别

• 当前级别：L2 源码/结构深度研究。
• 研究对象：shanraisshan/claude-code-best-practice。
• 证据来源：本目录 raw/ 下的 GitHub 元数据、README 快照和本地仓库工作树。
• 观察日期：2026-07-03。

L2 结论

shanraisshan/claude-code-best-practice 更像一个 Claude Code / Agentic Engineering 方法操作系统， 不是单篇教程。它把最佳实践、实现文档、编排工作流、agent teams、reports、tips、videos、 Claude 配置、Codex 配置和 MCP 配置放在同一个研究对象内，重点展示“如何把 AI 工程经验变成 可复用操作资产”。

对本仓最重要的启发是：方法论必须落到文件、配置、工作流、示例输出和报告中，否则就只是口号。

源码证据

• raw/repository/CLAUDE.md：Claude 项目级上下文入口。
• raw/repository/.mcp.json：MCP 配置入口。
• raw/repository/.claude/settings.json：Claude 配置。
• raw/repository/.codex/config.toml：Codex 配置。
• raw/repository/.codex/hooks.json：Codex hooks 配置。
• raw/repository/best-practice/claude-subagents.md：subagents 最佳实践。
• raw/repository/best-practice/claude-skills.md：skills 最佳实践。
• raw/repository/best-practice/claude-commands.md：commands 最佳实践。
• raw/repository/best-practice/claude-mcp.md：MCP 最佳实践。
• raw/repository/implementation/claude-subagents-implementation.md：subagents 实现文档。
• raw/repository/implementation/claude-goal-implementation.md：goal 实现文档。
• raw/repository/implementation/claude-skills-implementation.md：skills 实现文档。
• raw/repository/orchestration-workflow/orchestration-workflow.md：编排工作流说明。
• raw/repository/agent-teams/agent-teams-prompt.md：agent teams prompt。
• raw/repository/reports/why-harness-is-important.md：Harness 重要性报告。

关键机制

方法论被文件系统化

这个仓库把 best practice、implementation、workflow、reports 和 tips 分开。它说明成熟经验不应该 只放在 README，而应按用途进入不同层：原则、实现、编排、案例、报告和配置。

配置是研究对象的一部分

.claude/、.codex/ 和 .mcp.json 说明 AI 工程不是纯文档工作。模型入口、工具入口、hooks、 settings 和项目级上下文共同构成真实工作系统。

Agentic Engineering 强调编排

orchestration-workflow/ 和 agent-teams/ 体现了从单 Agent 交互走向多角色、多步骤、可复用流程 的趋势。这里的关键不是“多 Agent 数量”，而是任务边界、上下文分发、验收标准和输出归档。

报告层提供反思和二次沉淀

reports/ 把经验、问题和工具比较沉淀成独立材料。这对于本仓很重要：研究域的最终价值不是 收集资料，而是形成可复用判断。

可迁移模式

• 将经验分成 best-practice、implementation、workflow、reports 和 config 五层。
• 对每条方法论要求至少能落到一个文件、一个流程、一个示例或一个检查项。
• 将 hooks、settings、MCP 和项目上下文作为 AI 工程系统的一部分纳入治理。
• 对复杂任务使用 agent teams 或任务树时，必须先定义职责、边界、输入输出和验收标准。
• 重要结论需要有报告层，避免只在临时对话里消失。

对本仓的影响

本仓已经有 concepts、references、workflow、skills、research 和 governance 风格的资产雏形。 下一步应让这些层级更明确：

• principles 和 concepts 放底层认知。
• references 放可复用模板、清单和结构。
• workflow 放执行过程和门禁。
• skills 放 Agent 可执行能力。
• research 放未稳定的研究对象。
• reports 或 analysis 放研究判断和阶段复盘。

风险和待验证项

• 该仓库强烈绑定 Claude Code 生态，本仓不能直接照搬为通用事实。
• 个人方法论仓库容易混入偏好和风格判断，迁移时必须转成可验证契约。
• 本轮没有验证其中 hooks、MCP、agent teams 的真实运行效果。

下一步 L3 验证任务

• 在本仓补一份“方法论如何下沉到 concepts/references/workflow/skills”的分流规则。
• 对已有经验短句建立对应的可执行示例、检查项或技能入口。
• 把复杂研究任务的 agent teams 模式整理成本仓自己的任务编排契约。
• 将 Harness 相关结论与 research/harness/ 做交叉审计。