企业官网建设流程全解析

claude-howto 演进全解读：一份 Changelog 看懂 Claude Code 从 v2.0.0 到 v2.1.220 的功能变迁与文档精度治理

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto

claude-howto 是一套「可视化、示例驱动」的 Claude Code 实战指南仓库，覆盖从基础概念到高级 Agent 的完整链路，并内置可直接复制的模板。而仓库根目录下的 CHANGELOG.md 不只是一份普通的改动记录——它同时承载着两条时间线：仓库自身版本（v2.0.0 → v2.1.220-r2）与上游 Claude Code 版本（v2.1.84 → v2.1.220）的持续同步记录。读者通过这份文档，可以系统掌握 Claude Code 在模型、子代理、Hooks、MCP、权限模式等维度上近半年的真实演进脉络，也能看到一套文档型开源项目如何以"审计 + 版本化同步"的方式维持数千行技术内容的准确性。

一、如何阅读这份 CHANGELOG：文档定位与两条版本时间线

在深入细节之前，先理清这份 Changelog 的结构性信息，否则很容易被大版本号搞混。

claude-howto 教程覆盖范围。CHANGELOG 中反复出现的被修改文件，恰好勾勒出仓库的全貌：01-slash-commands/（斜杠命令）、02-memory/（记忆）、03-skills/（技能）、04-subagents/（子代理）、05-mcp/（MCP 服务器）、06-hooks/（钩子）、07-plugins/（插件）、08-checkpoints/（检查点/回滚）、09-advanced-features/（高级特性）、10-cli/（CLI），以及根级参考文档README.md、CATALOG.md、INDEX.md、QUICK_REFERENCE.md、LEARNING-ROADMAP.md、claude_concepts_guide.md、resources.md、STYLE_GUIDE.md和社区维护的多语言镜像（vi/、ja/、zh/、uk/）。

两条版本号不要混淆。仓库版本与上游 Claude Code 版本并非一一对应：

• 仓库曾在版本标签v2.4.0（2026-04-27）下同步的是上游 Claude Codev2.1.119；
• 上游存在被跳过的版本：如 v2.1.127、v2.1.130 从未公开发布，v2.1.213 的发布记录与 GitHub Releases 同样直接从 2.1.212 跳到 2.1.214；
• 最新的[v2.1.220-r2]（2026-08-04）是一次无上游版本变化的内部修正——审计确认 v2.1.220（2026-07-25）仍是当前最新 Claude Code 版本，本次同步只做仓库内部纠错。

因此，阅读时建议把条目中的"v2.1.xxx"一律理解为上游 Claude Code 的能力/行为变化时间点，而把仓库版本视为这批文档同步动作的批次标记。

二、模型家族与推理档位（effort）的持续更迭

CHANGELOG 最密集的技术事实集中在模型演进上，它直接决定了教程里所有模型表格、Compatible Models页脚与示例配置的取值。

2.1 默认模型的时间线

按 CHANGELOG 记录，Claude Code 各时期的默认模型与配套能力大致如下：

一个容易被忽视的例外：Microsoft Foundry 上opus别名仍解析到 Opus 4.6，这一差异写入了 10-cli/README.md 的模型表。与此同时，Claude Code 也引入了 Sonnet 5、Haiku 4.5（200k 上下文）与 Fable 5 等模型。CHANGELOG 特别记录了一处典型的模型表缺陷：claude_concepts_guide.md的 "Models & Reasoning Effort" 表曾漏掉 Claude Sonnet 5，尽管该文件自己的页脚已把它列为兼容模型。

2.2 Fast Mode（/fast）模型清单的两次翻转

/fast针对的模型清单随上游变动过多次：

• v2.1.142：Fast Mode 默认从 Opus 4.6 切到Opus 4.7，并新增CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1允许回退；
• v2.1.160：该环境变量被移除，成为no-op；
• v2.1.219：/fast适用于Opus 5 与 Opus 4.8，Opus 4.7 被移出清单。

这提醒使用者：任何关于"fast 模型是什么"的教程结论都必须标注版本时间点。

2.3 推理档位枚举与安全检查回退

• effort枚举完整值为low / medium / high / xhigh / max。CHANGELOG 曾在 v2.1.212 修正 04-subagents/README.md 的 frontmatter 表格漏列xhigh的问题——这是各文件间不一致的典型案例。
• v2.1.219 起，Opus 5 引入分层安全分类器回退：网络安全（cybersecurity）标记的请求会在 Opus 4.8 上重跑，而生物安全标记的请求直接拒绝（Opus 5 自带的生物学分类器无回退路径）。CHANGELOG 特别提示：使用本仓库security-review子代理与插件模板做渗透测试 / CTF 负载时会频繁触发该机制。

三、权限模式与 Auto 模式的纠偏史

权限语义是本仓库修正最多的领域之一，很多早期文档中的"虚构配置"在这里被逐步铲除。

3.1 从虚构模式名到真实 settings 键

• v2.0.0 明确废弃了虚构的Unrestricted / Confirm / Read-only模式名，统一为真实取值default / acceptEdits / plan / dontAsk / bypassPermissions（其中default后经 v2.1.160 区间改名为manual，QUICK_REFERENCE.md当时已落后 52 个版本还停留在旧名）；
• v2.1.220-r2 删除了一批配置示例中不存在的permissions.mode键（旧值default），统一改用permissions.defaultMode: "manual"。当前 config-examples.json 中 11 个示例全部使用真实 schema 键：permissions.defaultMode、permissions.allow/permissions.deny、env、hooks、fileCheckpointingEnabled、sandbox.*，模型 ID 也已更新到claude-opus-5/claude-sonnet-5。
• v2.1.220-r2 还纠正了 INDEX.md 对auto与dontAsk的反向描述：dontAsk并非"除风险操作外全部接受"的宽松模式，恰恰相反，它是最严格的模式——任何未预先批准的请求都会被自动拒绝。真正的宽松写入模式是acceptEdits一系。

3.2 Auto 模式：从 opt-in 到默认开启

Auto 模式的资格与开启方式历经多次翻转，CHANGELOG 逐条记录：

• 早期（v2.1.112 之前）：auto被标为 "Research Preview"，Max 用户在 Opus 4.7 上还需配合--enable-auto-mode；
• v2.1.158：Auto 模式以opt-in方式登陆 Bedrock / Vertex / Foundry，通过CLAUDE_CODE_ENABLE_AUTO_MODE=1开启；
• v2.1.207：开关反转——三大第三方云上 Auto 模式默认可用（面向 Sonnet 5、Opus 4.7/4.8、Fable 5），该环境变量从此刻起"接受但无效果"；
• v2.1.212 区间文档自我矛盾被修正：Auto 模式在所有套餐可用（仅受模型与 Provider 资格限制），Team/Enterprise 默认开启，管理员通过permissions.disableAutoMode退出（opt-out），而此前文档误写成 Owner 的 opt-in；
• v2.1.212 新增claude auto-mode reset子命令恢复默认 Auto 配置，裸/resume现在会打开历史会话选择器（含已删除会话）并以后台会话恢复。

CLI 入口同样被梳理：--enable-auto-mode标志早在 v2.1.111 就被移除（Auto 模式进入默认Shift+Tab循环），正确入口是--permission-mode auto。QUICK_REFERENCE.md、10-cli/README.md 中所有残留的旧 flag 用法都被更正。

3.3 计划模式与 Bash 分类器裁决

• v2.1.136 起，Plan 模式无条件阻止一切文件写入——即使存在匹配的Edit(...)allow 规则也不再放行，堵死了旧的行为绕过；需要写文件的工作流必须先退出计划模式（Shift+Tab）。
• v2.1.218 起，rm -rf /与rm -rf ~（含命令/进程替换内写法）由安全分类器裁决，不再弹权限对话框；Plan 模式叠加 Auto 时，对静态分析器无法证明只读的 Bash 命令也不再逐条询问（useAutoModeDuringPlan，默认开启）。
• 管理侧密钥autoMode.hard_deny（v2.1.136）用于无条件拦截某一类动作（如危险删除、对受保护分支的 force-push），hard-deny 规则不允许分类器协商，区别于可协商的soft_deny。

3.4 写入安全与绕过边界的持续收紧

• v2.1.160：即使处于acceptEdits，写 shell 启动文件（.zshenv、.zlogin、.bash_login、~/.config/git/）与可执行代码的构建配置（.npmrc、.yarnrc*、bunfig.toml、.bazelrc、.pre-commit-config.yaml、.devcontainer/）仍会弹确认——防止恶意命令执行链；
• v2.1.145 安全修复：Bash 裸环境变量自动放行漏洞被关闭。形如FOO=bar somecommand的命令，即使FOO=bar在 allowlist 中也不再自动放行，必须通过覆盖完整命令的Bash(...)权限规则显式放行（详见 06-hooks/README.md）；
• v2.1.121 / v2.1.126：--dangerously-skip-permissions的免提示写入范围扩展到.claude/skills/、.claude/agents/、.claude/commands/、.claude/、.git/、.vscode/与 shell 配置文件，但灾难性删除命令（rm -rf /等）依然强制询问。

四、子代理体系：嵌套深度、会话上限与命令语义演变

子代理（subagent）是 claude-howto 教程的核心模块之一（04-subagents/README.md），CHANGELOG 记录了一段极易反转的三段式历史。

4.1 嵌套（nesting）深度的三段式历史

从 v2.1.217 到 v2.1.220，嵌套默认行为连续反转了两次。为避免再次反转时文档崩坏，仓库在五处（04-subagents/README.md、CATALOG.md、10-cli/README.md、QUICK_REFERENCE.md）统一记录同一段三时代注记：

1. v2.1.172 – v2.1.216：子代理默认可嵌套，最深5 层，且无开关可改；
2. v2.1.217：嵌套改为默认关闭，需CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH显式开启（深度 1）；
3. v2.1.219：默认值改为深度 3，此时设置CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1的作用从"开启"反转为"关闭嵌套"。达到深度上限时，除 fork 外的所有子代理都不会再被授予Agent工具。

配套新增两类会话级上限：

• CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS（默认20）：并发运行子代理数上限；
• CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION（默认200）与CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION（默认 200）：单会话子代理孵化 / WebSearch 调用上限，/clear会重置。

4.2 /fork、/subtask 与 /branch 的语义澄清

CHANGELOG 用两次修正理清了这套命令的真实关系：

• /fork与/branch并非同一个命令的重命名：从 v2.1.77 到 v2.1.161 期间它们确实是别名关系，但此后分道扬镳——/fork生成继承对话的后台子代理，/branch则让你在原位切换到一份会话副本；
• v2.1.212 起/fork与/subtask的角色再次互换：/fork把当前对话复制进一个新的独立后台会话，原"fork 子代理"行为移交给了此前在仓库中完全缺席的/subtask。仓库据此在四个文件中完成纠正与补录。

4.3 子代理运行安全与协议

• 子代理输出扫描（v2.1.210）：Claude Code 会扫描子代理报告中的提示注入模式（伪造系统标签、捏造的对话轮次、权限绕过暗示）并将其中和——这是安全审查类 Agent 的底层保障；
• Task 工具mode参数弃用（v2.1.212）：子代理默认继承父会话的权限模式，Task 工具按调用传入的mode参数被忽略；
• subagent_type匹配对大小写与分隔符不敏感（v2.1.140）：code-reviewer、Code Reviewer、code_reviewer指向同一 Agent；
• stream-json 模式下--forward-subagent-text现在能带出深度 2+ 的嵌套子代理，以其孵化者的Agenttool_useid 为键；
• Agent 定义对 frontmatter 的要求也在收紧：Agent 名拒绝:（保留给插件命名空间），frontmatter 布尔值接受yes/no、on/off、1/0及大小写变体；Agent frontmatter 中的 hooks 需要所在目录先接受 workspace trust 才会运行；
• claude agents --json（v2.1.145）以机器可读 JSON 输出 Agent 列表，便于状态栏、会话选择器等脚本化工具消费。

4.4 调度与后台运行

--max-budget-usd从 v2.1.217 起不仅阻止新子代理孵化，还会中途终止已在运行的后台子代理；claude agents视图中Ctrl+T可钉住后台会话，空闲时保持存活、原地重启以应用更新、并在内存压力下晚于非钉住会话被回收。

五、Hooks：事件总数演进、退出码协议与典型修复

Hooks 是 CHANGELOG 中最具"工程事故现场感"的部分——这次同步修掉了两个会导致脚本"看似工作实则失效"的经典 bug。

5.1 事件总数：18 → 25 → 29 → 31

Hook 事件清单经历了多轮扩充与反复核对：v2.1.84 时期从 18 扩到 25；Setup事件（v2.1.138，用于一次性环境初始化）把它推到 29；v2.1.219 新增DirectoryAdded（在/add-dir或 SDKregister_repo_root控制请求注册新工作目录后触发），总数升到 30；最终在 v2.1.220-r2 的审计中逐名核对官方 Hook 清单，把此前分散在README.md、CATALOG.md、QUICK_REFERENCE.md、INDEX.md、resources.md五个文件中的"29"全部修正为31——README.md此前只枚举了 25 个名字，INDEX.md只列了 29 个。claude_concepts_guide.md的事件表还曾漏掉MessageDisplay（v2.1.152 就已存在的旧缺口）与新增的DirectoryAdded，修正后与 06-hooks/README.md 的事件表完全一致。

5.2 退出码协议：阻塞 = 2，非阻塞 = 1

本仓库 06-hooks/README.md 自己定义的退出码表中：exit 1 表示"非阻塞错误"，只有 exit 2 才表示阻塞。据此审计发现两个真实缺陷：

• pre-commit.sh 从未真正拦截过提交：脚本打印 "Commit blocked." 后，四个阻塞点全部exit 1——按协议这属于非阻塞错误，提交照样继续。修正后四处改为exit 2，并把拦截原因写入stderr（Claude Code 正是从 stderr 读取阻塞原因的）；
• dependency-check.sh 从未真正运行过：它从$1（命令行参数）读取目标路径，但 Hooks 的数据其实通过stdin 传入 JSON，于是路径恒为空、脚本立即退出。修正后改为从 stdin 解析file_path，与 format-code.sh 的做法保持一致。

这个教训值得任何写 Hook 的团队铭记：Hook 输入一律走 stdin JSON，永远不要假设参数$1会被传入。相关协议在 06-hooks/README.md 有完整约定（"Hook scripts receive the hook JSON payload viastdin"）。

5.3 决策字段与事件输入扩展

• permissionDecision的合法值为allow / deny / ask / defer；多 Hook 冲突时优先级为deny>defer>ask>allow，其中defer优雅退出以便后续恢复工具调用（修正前permissionDecision缺少defer一值）；
• Hookexec 形态（args: string[]，v2.1.139）：直接execve()派生，不经 shell 解析，与 shell 形态的command字段互斥；
• PostToolUse支持continueOnBlock: true（v2.1.139，把被拦截的工具结果以tool_result回传给 Claude，而非中断整轮）与duration_ms输入字段（v2.1.119）；
• 输入 JSON 新增effort.level（v2.1.133）；Bash 子进程可获得CLAUDE_CODE_SESSION_ID（v2.1.132，与 Hook 输入 JSON 的session_id对应）与CLAUDE_EFFORT（v2.1.133）；
• v2.1.141 新增terminalSequence输出字段，可发射原始 OSC 转义序列实现桌面通知、窗口标题与响铃；
• Stop/SubagentStop 输入字段新增background_tasks与session_crons（v2.1.145，用于判断是否应阻止带后台/定时任务的停止）；为避免坏 Hook 死循环，Stop Hook 连续阻塞达8 次即强制结束会话，可用CLAUDE_CODE_STOP_HOOK_BLOCK_CAP覆盖（v2.1.143）；
• v2.1.214 收窄了if:全局匹配：单段dir/**只匹配<cwd>/dir，跨任意深度须写**/dir/**；SessionStart的 fork 来源现在上报为"fork"而非"resume"。

仓库自带的 Hook 脚本也随之上了一课：context-tracker.py与context-tracker-tiktoken.py原先假定 128k 上下文窗口——而当下没有任何 Claude 模型是 128k，默认值被修正为1M并注明 Haiku 4.5 为 200k。

六、斜杠命令、技能（Skills）的命名治理与影子冲突

Slash 命令与技能是本仓库最大的内容族之一，命名与影子冲突（shadowing）问题贯穿各版本。

6.1 /code-review 改名风波与仓库的应对

• v2.1.146：内置/simplify技能改名/code-review，且是无别名硬改名——旧名字彻底失效。命令可选 effort 参数（/code-review high），v2.1.147 起可用--comment把发现作为 GitHub PR 内联评论发布；
• 由于 claude-howto 自己也维护一套本地 code-review 技能，为避免影子化（shadow）新内置命令，仓库把自己的技能目录从code-review改名code-review-specialist（见 03-skills/code-review-specialist/SKILL.md），并在 README 中说明了冲突原因与规避方法；
• v2.1.218：/code-review改为以后台子代理运行，审查工作不再占用主对话，且支持叠层斜杠命令继续作为其审查目标；/verify与/deep-research同样是仅显式调用（Claude 不再自行触发 deep-research）。

同类问题还发生在技能命名上：doc-generator的 SKILL.md 曾声明name: api-documentation-generator、refactor曾声明name: code-refactor——name:与实际目录不符会让复制进.claude/skills/的安装流程失效。同时被修正的还有三个非法技能名（Documentation Refactor、Setup CI/CD Pipeline、Expand Unit Tests，技能名只允许小写字母与连字符）和一个非标准tags:字段。

6.2 技能装载与覆盖规则

• 技能优先级此前在同一 README 里自相矛盾，现统一为enterprise > project > personal；
• context: fork技能默认background: true（v2.1.218），这与04-subagents中background: true强制后台的语义形成对照，文档特意写明默认值以免读者混淆；v2.1.145 还修复了context: fork在极端情况下触发无限循环的问题；
• skillOverrides在"on"/"off"之外新增"name-only"与"user-invocable-only"（v2.1.129）；技能内容中支持${CLAUDE_EFFORT}占位符（v2.1.120）解析当前 effort 档位；
• 仓库例子技能deep-research会影子化内置的/deep-research，已改名topic-research。

6.3 命令与技能数量清单的持续盘点

内置技能列表曾长期失真：CATALOG.md、QUICK_REFERENCE.md与03-skills/README.md各持一份互不一致的 5 项列表，v2.1.145 统一为规范 9 项（/batch、/claude-api、/debug、/fewer-permission-prompts、/loop、/run、/run-skill-generator、/simplify、/verify）；此后随着/code-review接棒/simplify、/deep-research等进入内置技能表，CATALOG.md的汇总又从误标的 9 修正为 10（总数 16）。QUICK_REFERENCE.md还曾把/voice、/browse误列为内置技能——两者其实都不是。斜杠命令侧同样经过"55+ 内置 + 5 内置技能"（v2.1.84）这类数量级的迭代，并出现过/simplify系列之外的命令改名，例如 v2.1.144 的/usage-credits（取代/extra-usage，别名保留）。

七、MCP：作用域选择、错误呈现与连接细节

CHANGELOG 在 MCP 维度贡献了一个重要补课：文档此前"介绍了 MCP 作用域却没有告诉读者如何选择作用域"。

7.1 --scope 标志与作用域表

05-mcp/README.md 补齐了缺失的--scope选择方式（含简写-s），作用域语义如下（注意旧称曾在版本间漂移：project曾叫local之类命名）：

7.2 配置正确性与可观测性

• 示例配置此前硬编码了凭据（postgresql://user:pass@localhost/mydb），违反模块自身"不要硬编码凭据"的规则，已改为${DATABASE_URL}环境变量占位；四个 MCP 示例配置也都补齐了"type": "stdio"字段；
• v2.1.219：claude mcp list与/mcp在连接失败时会报告 HTTP 状态码与错误文本，并警告配置值中隐藏的前后空白；headless 运行则通过 stream-json 的 init 事件暴露mcp_server_errors；
• v2.1.212：MCP 工具调用超过 2 分钟自动转后台，避免阻塞会话，阈值由CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS控制；
• v2.1.121：alwaysLoad: true让该服务器的所有工具跳过工具搜索延迟加载；
• v2.1.139：CLAUDE_PROJECT_DIR传入所有 MCP stdio 服务器的环境，插件与项目.mcp.json的command/args/env字段支持${CLAUDE_PROJECT_DIR}替换；
• MCP 服务器从 v2.1.132 起在/clear后保持连接；mcp_toolHook 类型（v2.1.118）、WebSocket MCP 传输（v2.1.84 区间）也纳入文档；
• 管理侧：allowAllClaudeAiMcps（v2.1.149）允许组织级放行 claude.ai 云 MCP 连接器；安全审计还修复了高层级 managed-settings 源缺少sandbox块时allowManagedDomainsOnly/allowManagedReadPathsOnly被忽略的问题（v2.1.126）。

八、配置 schema、检查点与沙箱设置的"去虚构化"

8.1 config-examples.json 的 schema 大修

v2.1.217 审计发现 config-examples.json 中全部 11 个示例使用了不存在的虚构字段（mode: "unrestricted"/"confirm"、planning.*、extendedThinking.*、headless.*、checkpoints.autoCheckpoint），以及过期的claude-opus-4-7模型 ID。重写后全部使用真实settings.json键：permissions.defaultMode、permissions.allow/deny、env、hooks、fileCheckpointingEnabled、sandbox.*，并换上当时最新的模型 ID。如今文件里的 11 个场景（开发、代码审查、学习、生产、CI/CD、安全审计、性能优化等）都可作为真实可用的起点配置。

8.2 检查点（Checkpoints）设置的补全

08-checkpoints/README.md 一度声称cleanupPeriodDays是唯一的检查点设置，实际至少还有：

• fileCheckpointingEnabled（默认true）：每次编辑前生成快照以便/rewind恢复，环境变量等价物为CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING；
• cleanupPeriodDays（默认 30）：保留会话历史与检查点的天数；v2.1.117 起该键同时管辖任务、shell 快照与备份四类磁盘缓存；
• 100 个检查点保留上限：即便在保留窗口内，超出最近 100 个快照也会被丢弃；
• v2.1.216：/rewind不再经由符号链接/硬链接恢复或删除文件——若被跟踪路径解析经过链接，则跳过并报告跳过的数量。

8.3 沙箱与后台隔离

• sandbox.filesystem.disabled（v2.1.216）：跳过文件系统隔离但继续强制网络出口管控；
• sandbox.network.strictAllowlist（v2.1.219）：沙箱命令访问未列入白名单的主机时直接拒绝、不再询问；
• worktree.baseRef（v2.1.133，默认"fresh"，从origin/<default>分支）与worktree.bgIsolation: "none"（v2.1.143，后台会话直接改当前工作副本而非隔离 worktree）；
• 新增sandbox.bwrapPath/sandbox.socatPath（v2.1.133，Linux/WSL）指定非标准位置的 bubblewrap / socat 可执行文件，默认走$PATH查找。

九、记忆系统与 AGENTS.md 的认知修正

02-memory模块在多个版本里被"祛魅"，CHANGELOG 记录了对记忆语义最彻底的澄清：

• 记忆文件是"拼接"而非"覆盖"：02-memory/directory-api-CLAUDE.md曾声称"覆盖根 CLAUDE.md"，实际子目录 CLAUDE.md 会与根文件一起拼接进上下文，不存在覆盖关系；claude_concepts_guide.md中错误的.claude/local/CLAUDE.md路径修正为./CLAUDE.local.md；
• 记忆层级一节推翻了虚构的"8 层严格优先级"模型，还原为验证过的结构：CLAUDE.md 与规则文件被拼接进上下文，managed-settings.d/属于settings.json机制而非 CLAUDE.md 机制；架构图此前混淆了 claude.ai 的 24 小时合成周期与 Claude Code 的连续自动记忆；
• 导入深度表述统一为"4 hops"（此前"5 levels"与"4 hops"并存）；记忆文件 frontmatter 从 v2.1.214 起带 ISOmodified时间戳；v2.1.216 起/memory的 GUI 编辑器不再阻塞会话；
• #前缀的快捷记法早已标记 Discontinued，但 README 里仍残留两处教程式描述，v2.1.212 全部移除，改为指向/memory与会话内自然语言记忆请求；
• CLAUDE.md 长度建议统一为"控制在几百行以内、越短越好"——两个文件的 300/500 行之争被裁决，原因是官方并不存在具体上限，两个数字都是编辑部措辞。

AGENTS.md 的定位修正尤其值得注意：claude-md技能曾把 AGENTS.md 描述成 Agent 定义格式，但它是跨工具的项目上下文文件，而且 Claude Code不会直接读取它——必须通过@AGENTS.md导入或符号链接引入。

十、CLI、插件生态与平台适配速览

将 CHANGELOG 中散落的 CLI / 平台条目归类，可得到如下能力演进：

• 新子命令族：claude plugin init <name>（v2.1.157，直接在.claude/skills脚手架化插件并自动装载）、claude plugin prune（v2.1.121，清理孤儿依赖）、claude plugin details（v2.1.139，插件清单 + 预估 token 成本）、claude project purge [path]（v2.1.126，删除项目全部状态，支持--dry-run/-y/-i/--all）、claude ultrareview [target]（v2.1.120，CI 非交互运行，--json/--timeout）、claude install [version]与claude auto-mode reset；
• 打印模式正名：虚构的claude-code --headless在 v2.0.0 被替换为真实的claude -p（print mode）；claude agentsAgent View（v2.1.139 起）提供完整的派发 flag 集：--cwd、--add-dir、--settings、--mcp-config、--plugin-dir、--permission-mode、--model、--effort、--dangerously-skip-permissions；
• 插件清单格式迁移：plugin.yaml→.claude-plugin/plugin.json（v2.1.0 区间）；插件放在.claude/skills可免 marketplace 自动装载；仅含顶层SKILL.md的插件以单技能呈现（v2.1.142）；spaced 斜杠命令（/myplugin review）解析为/myplugin:review（v2.1.138）；新增--plugin-url（v2.1.129）与会话级临时加载；
• MCP 配置路径规范化：~/.claude/mcp.json→.mcp.json（项目级）/~/.claude.json（用户级）；
• Windows / 云平台适配：Git for Windows / Git Bash 不再是必需（v2.1.120），PowerShell 成为默认 shell 工具（v2.1.126）；v2.1.143 起 Bedrock/Vertex/Foundry 上默认启用 PowerShell（-ExecutionPolicy Bypass），可用CLAUDE_CODE_USE_POWERSHELL_TOOL=0或CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1退出/让其遵守系统执行策略；
• Gateway 模型发现改为 opt-in（v2.1.129）：设置ANTHROPIC_BASE_URL不再自动拉取/v1/models，需额外设置CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1；
• 可访问性与终端：屏幕阅读器模式（--ax-screen-reader、CLAUDE_AX_SCREEN_READER=1、"axScreenReader": true，v2.1.208）；CLAUDE_CODE_FORCE_SYNC_OUTPUT（v2.1.129）修复 Emacseat等终端同步输出误检；/context不再把 ASCII 可视化灌进对话（每调用省约 1.6k token）；Ctrl+R 历史选择器默认跨项目，按 Ctrl+S 收窄到当前项目。

十一、比功能更重要的事：文档精度的工程化保障

把这份 CHANGELOG 当成一份"文档型开源项目的运维日志"来读，能提炼出大量可复用的工程实践，而这正是它与普通 Release Note 的最大区别。

版本化元数据页脚。仓库为每份受管 Markdown 文件设计了统一页脚（版本号 + 最后更新日期 +Compatible Models行）。一次审计发现 61 个文件还停留在仅含Last Updated的旧页脚或完全没有页脚，而个别模块 README（如02-memory/README.md）滞后于 v2.1.217。修复后全部 87 个受管文件统一上报 2.1.220。此前各版本也严格执行"bump every English doc's metadata footer"的批量操作。

数量类信息的全库盘点。跨文件统计是最容易失真的内容：CATALOG.md汇总表"自己都加不对"（Subagents 11→9、MCP 8→4、Hooks 8→11）；INDEX.md低估 Plugins（27→39）、Skills（21→23）、Hooks（9→12）等并漏掉三个 Hook 脚本与setup-auto-mode-permissions.py；一次误标把 Skills 写成 28、Plugins 写成 40。修正方法只有一个：以文件树为源逐文件清点。

交叉一致性检查的盲区。doc-generator/SKILL.md的代码栅栏曾提前闭合留下一处游离反引号块，导致示例一半渲染成实时 Markdown；而仓库的 check_markdown_rendering.py 只扫描 README 文件，因此两头都没拦住——审计的价值正在于覆盖自动化盲区。

正文示例与真实数据的对齐。一处演练示例在一份文件里报告 42 个 PR、另一份文件里却写着 47；Mermaid 图用了 STYLE_GUIDE 之外的非规范调色板。示例数字、图表配色这类"小问题"，恰恰是教程类仓库可信度的基石。

多语言镜像的同步纪律。vi/、ja/、zh/、uk/是社区维护的本地化副本，可能落后于英文源。CHANGELOG 每次同步都附 "Notes for translation maintainers"，明确列出哪些增量需要镜像（例如 P0/P1 结论只镜像受影响文件、--max-budget-usd澄清需镜像全部四种语言），避免无关大范围重译。

已知缺口透明化。仓库并不把问题都"悄悄改掉"——例如03-skills/.claude/skills/blog-draft/被确认是.gitignore中的本地测试草稿而非跟踪副本，CHANGELOG 把它如实记录在 "Known gaps (deferred)" 一节，避免后人误判为重复目录而清理。

十二、给读者的演进规律小结

纵向扫过整份 CHANGELOG，能归纳出 Claude Code 与 claude-howto 同步演进的几条规律，供使用者预判未来变化：

1. 默认值会被反复翻转，务必带版本号引用。子代理嵌套（关→开→默认 3 层）、Auto 模式（opt-in→默认）、默认 Opus 模型（4.8→5）、Fast Mode 模型清单都经历过反转；引用任何"默认行为"结论前先确认 v2.1.xxx。
2. 权限语义持续收紧，安全补丁密集。从 Plan 模式无条件禁写、Bash 裸环境变量漏洞关闭、到dontAsk严格语义澄清，安全边界总体向"更少自动放行"演进。
3. 命名与影子冲突是技能生态的持续痛点。内置技能改名（/simplify→/code-review）、name:与目录不一致、例子技能影子化内置命令——命名治理贯穿始终。
4. 文档即代码，同样需要 schema 校验。虚构配置键、虚构模式名、失真的数量清单最终都要靠"以官方资料与文件树为源"的审计来清理；自动化校验只能覆盖它看得到的地方。

想要逐条核对原文细节的读者，可继续深入 CHANGELOG.md 本体，并对照 06-hooks/README.md（Hook 事件表与退出码协议）、04-subagents/README.md（子代理嵌套历史）、05-mcp/README.md（MCP 作用域与配置）、08-checkpoints/README.md（检查点设置）以及 config-examples.json（真实 settings schema 示例）获得一手佐证。

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto