★ FEATURED ARTICLE 文档教程AI 技能【免费下载链接】claude-code-best-practicefrom vibe coding to agentic engineering - practice makes claude perfect项目地址https://gitcode.com/GitHub_Trending/cl/claude-code-best-practice点击查看免费下载这份学习旅程文档reports/learning-journey-weather-reporter-redesign.md记录了 claude-code-best-practice 仓库中演讲材料的一次重要重构方案从第 7 张幻灯片起用天气播报员weather reporterAgent这一贯穿始终的运行示例把 Agents、Skills、Context、CLAUDE.md、CommandsWorkflow 五大概念串联成一条完整叙事弧。读完本文你将掌握一套可复用的技术演讲编排方法——如何用一个真实可运行的示例把五个独立概念组织成先认识这个人再理解它会什么、怎么想、守什么规则、如何一键触发的教学路径并能对照仓库中已落地的天气系统源码.claude/agents/、.claude/skills/、.claude/commands/、orchestration-workflow/验证每一个环节的真实实现。一、为什么需要一条贯穿始终的叙事弧仓库的核心定位是from vibe coding to agentic engineering见 README.md 与 CLAUDE.md演讲需要在有限篇幅内讲清楚五组彼此关联但又各成体系的概念Agents专职角色、Skills技能、Context上下文/工作记忆、CLAUDE.md规则手册、CommandsWorkflow触发与编排。旧版演讲的问题在于每个主题单独成段听众要反复切换心智模型。重构方案给出的解法是——让天气播报员先出场再用它的日常工作去承载后续所有概念先与播报员见面Agents→ 理解它掌握什么技能Skills→ 理解它能同时记住多少东西Context→ 理解它上岗前要读的规则手册CLAUDE.md→ 最后看到一条命令如何把这一切串起来CommandsWorkflow。这条叙事弧与 TOC 的可见顺序Agents → Skills → Context → CLAUDE.md → Commands严格对齐听众始终带着同一个心智模型学习负担大幅降低。二、章节重映射从六段式到五段式原文档给出了完整的当前章节 → 新章节映射表这是重构的第一份蓝图当前章节当前页码动作新位置Topic 1: Context7-11第 7 页为分节页移到 Topic 3slides 17-21Topic 2: CLAUDE.md12-17第 12 页为分节页移到 Topic 4slides 22-27Topic 3: Agents18-23第 18 页为分节页移到 Topic 1slides 7-12Topic 4: Skills24-29第 24 页为分节页移到 Topic 2slides 13-18Topic 5: Commands30-32第 30 页为分节页与 Workflow 合并为 Topic 5slides 28-32Topic 6: Workflow33-36第 33 页为分节页并入 Commands 章节不再独立分节页结束页37保留更新副标题slide 33重排后是否需要删减幻灯片文档内部做过两次核算第一次粗略算成 33 张去掉 Workflow 分节页及 3 张内容页随后逐段复核得出最终结论保留全部 37 张零删减。Workflow 分节页不再承担第六个 Topic的职责而是通过去掉其data-level属性降级为 Commands 章节内部的一个章节视觉过渡页。需要说明的是这份文档是重构的规划蓝图其中 7-37 的页码是方案自洽的规格数字仓库中当前实际的演讲 HTMLpresentation/claude-code-best-practice/index.html已经过后续迭代例如现文件末尾的 workflow 幻灯片已位于data-slide54、data-slide55因此在实施时应以规划语义为准、与实际 DOM 结构做核对而不是照搬页码字面值。三、LEVELS 映射与 journey bar 的取舍演讲 UI 中有一条学习旅程进度条journey bar由每张幻灯片上的data-level驱动等级键与进度百分比一一对应。重构中最大的 UI 决策是Workflow 等级去留第一版思路彻底删除workflow键进度条最高只到commands83%。否决理由结尾章节进度条只填到 83% 而非 100%收尾观感不佳。最终决策commands83%与workflow100%两个键全部保留Commands 分节页挂data-levelcommands原 Workflow 分节页改挂data-levelworkflow作为 Commands 章节内部的高潮过渡页。这样内容虽然重新排序但 LEVELS 结构零改动journey 刻度ticks也原样保留。这一等级键驱动进度条的机制在仓库的姊妹演讲 presentation/2026-04-25-gdg-kolachi-cli-claude-code-gemini/index.html第 2662-2670 行中有直接实现佐证LEVEL_LABELS对象恰好维护了agents、skills、context、claude-md、commands、workflow六个键updateLevelBadge会在分节页的 h1 上动态追加等级徽标showSlide则负责刷新进度条与计数。这份源码与文档中6 个 level 键全部保留、无增删的簿记结论完全吻合。四、Slide-by-Slide 内容大纲五大主题的逐页设计4.1 前 6 页保持不变仅更新 TOC 跳转目标第 1-6 页标题页、Boris GIF、Vibe→Agentic 过渡、What is Vibe Coding、好/坏 Prompt 对比、TOC内容不动但第 6 页 TOC 各行的goToSlide(n)目标必须随新顺序更新行主题旧目标新目标行 1Agents187行 2Skills2413行 3Context719行 4CLAUDE.md1225行 5Commands3030不变4.2 Section 1Agentsslides 7-12——The PersonSlide 7分节页data-levelagentsTopic 1标题 Agents — The Weather Reporter副文案点题An agent is Claude playing a specific role. Meet the weather reporter — a specialist hired to fetch and report weather data for Dubai.Slide 8 The Restaurant Kitchen沿用普通提示词 在陌生厨房里乱喊Agent 找到专门的厨师的类比把示例统一换成天气播报员保留普通提示 vs 天气 Agent双栏对比卡片。Slide 9 Prompting vs. Agent — Side by Side对比表格原样保留天气示例本身已很贴切。Slide 10 Agents Get Their Own Brain保留 Thariq 的技巧并把它锚定到天气播报员the weather reporter works in their own brain — all that web fetching stays out of yours.播报员在自己的大脑里完成所有抓取不污染你的上下文。Slide 11 How to Create Your Own Agent保留/agents创建流程代码块更新为真实的weather-agent.md路径。Slide 12 Agent Config Fields保留字段表格新增一个高亮框展示skills: [weather-fetcher]字段的实际用法。仓库中的真实实现正是这段大纲的成品。.claude/agents/weather-agent.md 展示了该 Agent 的完整 frontmatterallowedTools只放行Read与Skill故意不给任何网络工具、model: sonnet、color: green、maxTurns: 5、permissionMode: acceptEdits、memory: project并通过skills: - weather-fetcher把技能预载入上下文。其正文用Execution Contract不可协商明确禁止 Agent 自行调用WebFetch/WebSearch/curl或把技能内容内联执行——这正是第 10 页Agent 有独立大脑在工程上的强制手段。各配置字段name、description、tools、model、permissionMode、maxTurns、skills、mcpServers、hooks、memory、background、effort、isolation、color的权威说明可参考 CLAUDE.md 的 Subagent Definition Structure 一节。4.3 Section 2Skillsslides 13-18——What the Reporter KnowsSlide 13分节页data-levelskillsTopic 2标题 Skills — What the Weather Reporter Knows副文案Our reporter has two: fetch the data, and render it as a card.Slide 14 The Training Manual把原来的 Shayan 示例替换为天气播报员的两项技能weather-fetcher去取温度和weather-svg-creator画视觉卡片。Slide 15 When to Turn Something Into a Skill保留 Boris 的技巧并把这两个技能列为示例。Slide 16 Why Separate Agents and Skills?强调 weather-agent 这个人weather-fetcher 它的训练内容。Slide 17 How to Create Your Own Skill代码块已展示真实的weather-fetcherSKILL.md 内容原样保留。Slide 18 Skill Config Fields新增注释——user-invocable: false设置在 weather-fetcher 上因为它是仅供 Agent 内部使用的技能。实现侧完全对得上。打开 .claude/skills/weather-fetcher/SKILL.md 可以看到user-invocable: false从/命令菜单中隐藏只作为后台知识、allowed-tools: WebFetch(*)正文给出 Open-Meteo 的免 API Key 抓取指令与迪拜坐标latitude 25.2048, longitude 55.2708支持 Celsius/Fahrenheit 两种单位而 .claude/skills/weather-svg-creator/SKILL.md 则是标准的独立技能——接收上下文中的温度与单位按 reference.md 的模板写出 orchestration-workflow/weather.svg 和 orchestration-workflow/output.md。关于技能 frontmatter 的完整字段name、description、argument-hint、disable-model-invocation、user-invocable、allowed-tools、model、context: fork、agent、hooks同样可查阅 CLAUDE.md 的 Skill Definition Structure 一节。4.4 Section 3Contextslides 19-23——The Reporters BrainSlide 19分节页data-levelcontextTopic 3标题 Context — The Reporters Brain文案引导Now that youve met the reporter and know their skills, lets understand what they can actually hold in mind at once.Slide 20 Claudes Brain保留context-window.jpeg图示新增一句与播报员的绑定When the weather-agent is dispatched, it gets its own fresh brain — and weather-fetcher is pinned into it at startup.Agent 被派出时获得全新的大脑weather-fetcher 在启动时就被钉进这个大脑。Slide 21 What Loads at Session Start保留context.jpg绑定播报员At startup, Claude knowsaboutweather-fetcher (description only). When the command runs, the full skill content is loaded into the agents brain.——这是渐进式披露progressive disclosure的直观表达启动时只加载技能描述命令真正运行时才把完整技能内容装入大脑。Slide 22 Keep the Brain Clear保留分支点branching point决策表。Slide 23 How to Manage Your Context保留/context、/compact、/clear三个管理命令的实操演示。第 20-21 页引用的两张上下文示意图均存在于仓库中presentation/assets/concepts/context/context-window.jpeg 与 presentation/assets/concepts/context/context.jpg重构的资产清单明确标注它们原样保留、仅随幻灯片重新编号。4.5 Section 4CLAUDE.mdslides 24-29——The Pocket RulebookSlide 24分节页data-levelclaude-mdTopic 4标题 CLAUDE.md — The Reporters Pocket Rulebook文案The reporter consults this at the start of every shift — even though their brain resets overnight.大脑每天重置但上岗前仍会翻阅这本口袋规则书。Slide 25 The Employee Handbook改用播报员框架——CLAUDE.md 是播报员开播前必读的规则书always report in Celsius unless asked, always cite the source.Slide 26 How to Create Your CLAUDE.md保留/init一键初始化流程。Slide 27 Grow CLAUDE.md With Every Mistake保留 Boris 的建议每次犯错都把它沉淀进 CLAUDE.md。Slide 28 What Goes in CLAUDE.md保留代码块新增天气专属规则的注释示例。Slide 29 How CLAUDE.md Loads原样保留。仓库的实践依据充分仓库根目录的 CLAUDE.md 本身就是这份规则书的一个活样例其中明确写着Keep CLAUDE.md under 200 lines per file for reliable adherence单文件控制在 200 行以内以保证可靠遵循——这正是第 25-27 页想传达的工程经验规则书要短、要随每次错误生长、要在会话开始时加载。此外 .claude/rules/markdown-docs.md 展示了带paths:frontmatter 的规则文件如何惰性加载只在你触碰匹配文件时才载入与 CLAUDE.md 的每会话全量加载形成对比可作为第 29 页CLAUDE.md 如何加载的延伸讲解。4.6 Section 5Commands Workflowslides 30-36——The TriggerSlide 30分节页data-levelcommandsTopic 5标题 Commands — The Trigger文案精炼概括全链路One word kicks off the whole chain./weather-orchestrator→ agent → skill → SVG card.Slide 31 Commands — The Entry Point保留已引用 weather-orchestrator。Slide 32 How to Create Your Own Command保留代码块已展示weather-orchestrator.md。Slide 33Workflow 子章节data-levelworkflow章节编号文字从 Topic 6 改为 Putting It All Together标题改为 Workflow — All Five Pieces Together文案Watch the weather reporter example run from one keystroke to SVG card output. 保留data-levelworkflow使进度条填满至 100%。Slide 34 Command → Agent → Skill保留代码块流程示意图已完美贴合示例。Slide 35 Two Ways Skills Are Used保留双栏对比——预载技能preloaded作为 Agent 领域知识注入vs 直接调用direct invocation命令通过 Skill 工具即时调用。Slide 36 How to Wire Your Own Workflow保留本身即以天气工作流为例。Slide 37结束页副标题改为 Five concepts, one running example正文同步回指天气播报员叙事弧。这段高潮在仓库中有完整的可运行成品。命令入口 .claude/commands/weather-orchestrator.md 定义了不可协商的执行契约必须用AskUserQuestion先问用户要 Celsius 还是 Fahrenheit必须通过 Agent 工具委托weather-agentsubagent_type: weather-agentmodel: haiku只有拿到数字温度后才允许调用weather-svg-creator任何一步失败都fail-closed立即停止并向用户报告绝不擅自 improvisation。第 35 页讲的两种技能用法在 orchestration-workflow/orchestration-workflow.md 里有系统级阐述Agent Skill预载weather-fetcher在 Agent 启动时以领域知识形式注入上下文Agent 按其指令执行不做动态调用Skill直接调用weather-svg-creator由命令通过Skill(skill: weather-svg-creator)即时调用在命令上下文里独立执行直接消费上下文中已有的温度数据。完整的调用链如下引自 orchestration-workflow/orchestration-workflow.md 的流程示意图一次真实执行的产物就落在 orchestration-workflow/output.md 中当前示例输出为 89.3°F含 SVG 卡片引用而 orchestration-workflow/weather.svg 即最终视觉卡片。仓库内实际运行的录制 GIForchestration-workflow/orchestration-workflow.gif也被当前演讲的 workflow 幻灯片presentation/claude-code-best-practice/index.html 中data-slide55用作端到端运行演示与重构方案中Workflow in action的设计一脉相承。另外weather-agent 还配置了memory: project历史读数会持久化到 .claude/agent-memory/weather-agent/MEMORY.md 与readings.md这为第 22 页Keep the Brain Clear与 Agent 记忆管理提供了真实样例。五、资产复用清单重构不需要新增素材现有资产几乎全部复用资产当前位置新位置动作context-window.jpegSlide 8Claudes BrainSlide 20内容不变重新编号保留无需改动context.jpgSlide 9What Loads at Session StartSlide 21内容不变重新编号保留无需改动!/claude-jumping.svgSlides 1、页眉不变无操作!/root/boris-slider.gifSlide 2不变无操作两张上下文示意图的宿主幻灯片只是从 8/9 重新编号为 20/21图片本身原地不动——这保证了视觉资产与叙事弧同步迁移时零损耗。六、簿记影响三张必须同步的账本重构牵一发动全身以下三处若不同步更新跳转与进度显示就会错乱1. 新分节页位置与data-level分配幻灯片主题data-level7Agentsagents13Skillsskills19Contextcontext25CLAUDE.mdclaude-md30Commandscommands33Workflow 子章节workflow2. 第 6 页 TOC 的goToSlide目标见 4.1 节表格Agents 18→7、Skills 24→13、Context 7→19、CLAUDE.md 12→25、Commands 30→303. journey 刻度与 LEVELS 映射——均无需改动journey tick 轨道自上而下本来的顺序是 Workflow、Commands、Skills、Agents、CLAUDE.md、Context恰好是叙事弧的倒序顶部 最高层级 最后达成因此不需要动LEVELS 的 6 个键context、claude-md、agents、skills、commands、workflow也一个不增、一个不减。七、实现路线单文件 HTML 的七步手术演讲是一个单一大 HTML 文件presentation/claude-code-best-practice/index.html而现有幻灯片顺序与新叙事弧不符最干净的实现方式是七步顺序执行剪切粘贴重排把各 slide div 按新顺序拼接7-12 原 18-2313-18 原 24-2919-23 原 7-1124-29 原 12-1730-37 不变顺序重编号所有data-slide属性按 1、2、3… 依次重排更新分节页data-level按第 6.1 节的分配表逐页校正更新分节文案分节页的章节编号文本与 h1 标题同步替换更新 TOC 跳转第 6 页各行的goToSlide目标按新页码改写更新 Workflow 过渡页原第 33 页的章节编号文本从 Topic 6 改为 Putting It All Together定向内容编辑按各小节大纲把需要天气播报员框架化的文案逐处替换。总页数保持37不变。对照当前 HTML 中goToSlide函数presentation/claude-code-best-practice/index.html第 2743 行与data-slide/data-level的既有使用模式这套手术步骤与现有代码结构完全兼容。八、歧义与决策记录文档在收尾处明确给出结论All ambiguities have been resolved above.——所有悬而未决的问题Workflow 等级去留、分节页是否降级、页数是否精简、LEVELS 是否改动都在前文逐项拍板页数不删任何幻灯片37 张全保留Workflow 分节页保留但摘掉第六个 Topic身份降级为 Commands 章节内的视觉过渡页LEVELS6 键全保留workflow100%通过挂在过渡页上来兑现进度条满格实施按七步法直接推进无需进一步澄清。九、这套方法论的复用价值抛开天气示例本身这份重构方案示范了一个可迁移到任何技术演讲的编排原则用一个贯穿始终的、真实可运行的示例作为所有抽象概念的锚点。仓库的做法尤其值得借鉴——它不是虚构一个 demo而是把示例真正做成了可执行的工程系统Agent、两个 Skill、一条 Command、一份编排文档、真实输出产物让演讲的每一页都能指回仓库里的真实文件。当你下次需要讲 Agents/Skills/Context/CLAUDE.md/Commands 这类相互关联的概念时可以照搬这条路径先让角色出场 → 再讲它的能力 → 它的记忆 → 它的规则 → 最后用一条命令把全部串起来并用story 弧顺序 TOC 顺序的约束来校验每张幻灯片的落位用data-level这类 UI 账本保证跳转与进度展示永远自洽。赞分享文档教程AI 技能【免费下载链接】claude-code-best-practicefrom vibe coding to agentic engineering - practice makes claude perfect项目地址https://gitcode.com/GitHub_Trending/cl/claude-code-best-practice点击查看免费下载相关推荐Cherry Studio Claude Code 工具声明式注册表单一事实来源架构设计与源码落地Cherry Studio Claude Code 工具声明式注册表单一事实来源架构设计与源码落地 本文基于 CherryHQ/cherry studio 仓人工智能大模型AI 应用交互助手本地部署学习 Harness 工程以五子系统框架深度解读 Claude Code 的 agentic harness 设计学习 Harness 工程以五子系统框架深度解读 Claude Code 的 agentic harness 设计 Claude Code 是 AnthropClaude Code Game Studios 叙事团队编排技能team-narrative实战指南五阶段管线、并行委派与一致性治理Claude Code Game Studios 叙事团队编排技能team narrative实战指南五阶段管线、并行委派与一致性治理 在 ClaudeAI 技能/插件游戏开发AI 应用上一篇如何高效实现Cursor Pro功能解锁终极技术方案解析下一篇3分钟学会免费解锁WeMod高级功能的终极指南 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
