教程文档【免费下载链接】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.md 是 Claude Code 会话中唯一被自动注入的项目上下文文件它的质量直接决定 AI Agent 对代码库的理解深度与协作效率。本文以 claude-howto 仓库中的claude-mdSkill03-skills/claude-md/SKILL.md为骨架系统讲解如何以create、update、audit三种模式创建、优化与审计 CLAUDE.md并借助本仓库的记忆体系02-memory/README.md与真实模板文件让你读完即可上手写出少而精、全会话通用、渐进式披露的项目接入文档。什么是 claude-md Skillclaude-md是一个文件系统型 Agent Skill其职责在 frontmatter 中定义得非常明确--- name: claude-md description: Create or update CLAUDE.md files following best practices for optimal AI agent onboarding ---它的核心使命是按照最佳实践创建或更新 CLAUDE.md 文件实现最优的 AI Agent 项目接入onboarding。在 claude-howto 仓库的 Skills 体系中它与 blog-draft、code-review-specialist、refactor 等 Skill 并列存放在03-skills/目录下属于参考型 任务型混合 Skill既注入项目文档写作的领域知识也提供create/update/audit三种明确的可执行任务流程。与一次性 Prompt 不同Skill 采用渐进式披露Progressive Disclosure加载元数据name description在会话启动时即被载入约 100 tokensSKILL.md 正文在被触发时才加载控制在 5k tokens 以内配套资源按需加载、规模近乎无上限。这意味着把 claude-md 安装进~/.claude/skills/或项目.claude/skills/后平时几乎不占上下文只有当用户提到 CLAUDE.md、项目文档或 AI 接入相关话题时才被激活。关于 Skill 的加载机制与安装路径可进一步参阅 03-skills/README.md。用户输入模式Skill 通过$ARGUMENTS接收用户输入并根据内容分流到三种模式参数行为create从零创建新的 CLAUDE.mdupdate改进已有的 CLAUDE.mdaudit分析并报告当前 CLAUDE.md 的质量具体路径如src/api/CLAUDE.md在指定目录创建/更新目录级 CLAUDE.md调用示例/claude-md create # 为当前项目新建 CLAUDE.md /claude-md update # 优化现有 CLAUDE.md /claude-md audit # 输出质量审计报告 /claude-md src/api/CLAUDE.md # 为 src/api 目录生成专属说明如果$ARGUMENTS为空Skill 按默认的create流程执行。核心原则CLAUDE.md 为何必须少而精Skill 开篇即点明一个关键事实LLM 是无状态的stateless。CLAUDE.md 是唯一一份会被自动纳入每次对话的文件它是 AI Agent 了解代码库的第一入口也是唯一入口。因此它承载的是每一次会话都必然相关的信息而非某一任务的临时说明。四条黄金法则The Golden Rules少即是多Less is More前沿 LLM 大约能遵循 150200 条指令而 Claude Code 的系统提示词本身已占用约 50 条。留给你的 CLAUDE.md 的空间极其有限必须聚焦、精炼。全会话通用Universal Applicability只收录与每一次会话都相关的信息。任务专属指令应拆分到独立文件中如 Skill、.claude/rules/*.md而不是塞进 CLAUDE.md。别把 Claude 当 Linter 用Dont Use Claude as a Linter代码风格规范会膨胀上下文并削弱指令遵循能力。格式与风格问题应交给确定性工具prettier、eslint 等解决Claude 只负责业务逻辑层面的判断。绝不自动生成Never Auto-GenerateCLAUDE.md 是整个 AI 工作流中杠杆率最高的文件必须由人手工精心撰写而不是让工具批量生成模板。仓库层面同样印证了这条原则——claude-howto 根目录的 CLAUDE.md 仅 60 余行却完整覆盖了仓库类型说明、关键命令、架构地图、硬性规则、工作流偏好与 token 效率约定是一个贴近实战的少而精范例。精简度与遵循度的实证依据02-memory/README.md 给出了更具体的量化结论Keeping CLAUDE.md Small一节经验法则CLAUDE.md 控制在 200 行以内。超过后文件仍会全量加载但指令遵循度随体积增长而下降。每一行都会在每一次会话中与无关任务争夺注意力所以把一切写进 CLAUDE.md是错误方向。当文件开始膨胀时正确的做法是把内容搬出去而不是删减措辞内容类型应该放哪原因多步骤流程Skill 目录按需加载只在相关时出现目录/文件类型专属规则.claude/rules/*.md带paths:frontmatter按 glob 限定作用域触碰匹配文件时才加载参考资料与长示例Skill 的references/目录仅在 Skill 需要时读取关于你的记忆Auto memory默认开启由 Claude 自动写入与加载需要注意一个常见误区path导入可以组织大型 CLAUDE.md但不能节省上下文——被导入文件在加载时同样会被完整拉入。真正能减少加载量的是把内容拆进按路径作用域生效的 rules 文件。此外v2.1.206 的/doctor命令会在 CLAUDE.md 膨胀到失去实用性时介入检查并提出精简建议。针对 Opus 5 / Fable 5 的特别提醒旧式指南常鼓励在 CLAUDE.md 里写做完必须跑测试务必复查工作之类的验证提醒。在 Claude Opus 5 和 Fable 5 上这类语句会引发过度验证——Claude 反复重查已经正确的工作白白消耗轮次与 token。应删除这类提醒改为陈述目标并让 Claude 自行判断真正非显而易见的需求如集成测试需要先启动 Docker属于信息而非提醒应当保留。执行流程从项目分析到文件落盘Skill 将 CLAUDE.md 的产出过程拆成七个阶段每个阶段都有明确的动作清单。阶段 1项目分析Project Analysis动手写作前先摸清项目现状检查已存在的 CLAUDE.md 文件根级./CLAUDE.md或.claude/CLAUDE.md目录级**/CLAUDE.md全局用户配置~/.claude/CLAUDE.md识别项目结构技术栈语言、框架、项目类型monorepo、单体应用、库、开发工具包管理器、构建系统、测试运行器。审阅现有文档README.md、CONTRIBUTING.md、package.json、pyproject.toml、Cargo.toml等。这一步决定了 CLAUDE.md 的既有事实避免重复收录 README 或包清单中已有的信息。阶段 2内容策略——WHAT / WHY / HOW 三维框架Skill 建议围绕三个维度组织 CLAUDE.md 内容这套框架尤其适合 monorepo 与复杂项目WHAT技术与结构技术栈总览、项目组织方式monorepo 尤其重要、关键目录及其用途。WHY目的与上下文项目做什么、某些架构决策为何如此、每个主要组件的职责。HOW工作流与约定开发工作流bunvsnode、pipvsuv等、测试流程与命令、验证与构建方法、关键陷阱gotchas与非显而易见的硬性要求。阶段 3渐进式披露策略Progressive Disclosure大型项目建议创建agent_docs/目录把细节沉淀为独立文件agent_docs/ |- building_the_project.md |- running_tests.md |- code_conventions.md |- architecture_decisions.md然后在 CLAUDE.md 中只引用这些文件For detailed build instructions, refer to agent_docs/building_the_project.md关键技巧使用file:line引用代替代码片段避免上下文过期——代码会被改而文件定位引用会始终指向最新内容。阶段 4质量约束Quality Constraints创建或更新 CLAUDE.md 时必须遵守五条约束目标长度控制在几百行以内越短越好无风格规则删除一切 lint / formatting 类指令无任务专属指令迁移到独立文件无代码片段改用文件引用无冗余信息不重复 package.json 或 README 里已有的内容。阶段 5必备章节模板Essential SectionsSkill 给出了可直接套用的骨架# Project Name Brief one-line description. ## Tech Stack - Primary language and version - Key frameworks/libraries - Database/storage (if any) ## Project Structure [Only for monorepos or complex structures] - apps/ - Application entry points - packages/ - Shared libraries ## Development Commands - Install: command - Test: command - Build: command ## Critical Conventions [Only non-obvious, high-impact conventions] - Convention 1 with brief explanation - Convention 2 with brief explanation ## Known Issues / Gotchas [Things that consistently trip up developers] - Issue 1 - Issue 2仓库中的 project-CLAUDE.md 正是这一模板的完整落地包含 Project Overview名称、技术栈、团队规模、Architecture用docs/architecture.md等导入、Development Standards代码风格、命名、Git 工作流、测试、API、数据库、部署、Common Commands 表格、Team Contacts、Known Issues Workarounds、Related Projects——可复制到自己的项目根目录直接改写使用。个人偏好则可参考 personal-CLAUDE.md目录级规则参考 directory-api-CLAUDE.md。阶段 6必须避开的反模式Anti-Patterns不要在 CLAUDE.md 中包含代码风格指南交给 linter如何使用 Claude 的说明文档对显而易见模式的长篇解释复制粘贴的代码示例通用最佳实践口号如写好代码特定任务的指令自动生成的内容冗长的 TODO 列表。阶段 7验收清单Validation Checklist落盘前逐项核验控制在几百行以内越短越好每一行都适用于所有会话无风格 / 格式化规则无代码片段改用文件引用所有命令都验证过可用复杂项目使用了渐进式披露关键陷阱gotchas已记录与 README.md 无冗余。三种模式的输出流程Skill 对create、update、audit三种模式给出了不同的工作流核心差异在于改与不改create或默认分析项目按上述结构起草 CLAUDE.md将草稿提交用户审阅获得批准后写入合适的位置。update读取现有 CLAUDE.md对照最佳实践审计识别三类变更需删除风格规则、代码片段、任务专属内容需压缩冗余或冗长的段落需补充缺失的必备信息提交变更方案供审阅批准后应用变更。audit读取现有 CLAUDE.md生成报告包含当前行数 vs 目标行数全会话通用内容占比百分比发现的反模式清单改进建议只报告、不修改文件。注意 update 与 audit 的边界update 会动手改文件audit 只输出诊断报告。在不确定时优先 audit把改动决定权留给用户。内存层级CLAUDE.md 在系统中的位置要写出合格的 CLAUDE.md还需理解它在 Claude Code 内存体系中的层级。据 02-memory/README.mdCLAUDE.md 文件按作用域从宽到窄存在多个位置按加载顺序排列注意这些文件是拼接进上下文而非互相覆盖作用域位置用途Managed policy受管策略macOS/Library/Application Support/ClaudeCode/CLAUDE.mdLinux/WSL/etc/claude-code/CLAUDE.mdWindowsC:\Program Files\ClaudeCode\CLAUDE.md组织级指令无法被个人设置排除User instructions用户指令~/.claude/CLAUDE.md跨项目的个人偏好Project instructions项目指令./CLAUDE.md或./.claude/CLAUDE.md团队共享、纳入版本控制Local instructions本地指令./CLAUDE.local.md个人项目专属偏好建议加入.gitignore目录树内的发现机制Claude Code 从工作目录向上遍历foo/CLAUDE.md先于foo/bar/CLAUDE.md加载——离启动目录更近的指令在上下文中出现得更晚更近于上下文末尾而非更高优先级。工作目录之下子目录里的 CLAUDE.md 则按需加载当 Claude 读取该子目录文件时才载入。子代理Subagent的内存作用域可通过定义文件中的memoryfrontmatter 限定memory: user # 仅加载用户级内存 memory: project # 仅加载项目级内存 memory: local # 仅加载本地内存目录级 CLAUDE.md 应比根级更聚焦。以 directory-api-CLAUDE.md 为例它开头就声明本文件是对根级 CLAUDE.md 在/src/api/下的补充内存文件是拼接而非覆盖Claude Code 在读取该子树文件时按需加载本文件随后只讲 API 模块专属的请求校验、鉴权、响应格式、分页、限流与缓存规范——这正是Universal Applicability原则在目录层级的应用。 导入语法避免重复、引用既有文档CLAUDE.md 支持path/to/file语法引入外部内容避免复制粘贴造成的维护漂移# Project Documentation See README.md for project overview See package.json for available npm commands See docs/architecture.md for system design # 使用绝对路径导入主目录文件 ~/.claude/my-project-instructions.md导入特性要点详见 02-memory/README.md相对路径与绝对路径均支持相对路径以包含该导入的文件所在位置为基准解析递归导入支持最大深度4 跳首次从外部位置导入会触发审批对话框安全机制导入指令在 markdown 代码跨段或代码块内不生效因此在示例中书写它们是安全的被引用内容会自动纳入 Claude 的上下文。AGENTS.md 处理跨工具项目上下文文件Skill 专门处理了 AGENTS.md 场景。自 v2.1.277 起Claude Code 将AGENTS.md直接作为项目指令读取——但仅当工作目录及其上每一级目录都不存在CLAUDE.md、.claude/CLAUDE.md或CLAUDE.local.md时。~/.claude/CLAUDE.md、受管 CLAUDE.md 和.claude/rules/不计入该检查会与胜出的项目文件一并继续加载。读取行为由/config中的Project instructions设置控制四个取值取值效果claude-md-or-agents-md默认——仅在找不到 CLAUDE.md 文件时读取 AGENTS.mdclaude-md-and-agents-md两者同时存在时都读取claude-md只读 CLAUDE.md 文件忽略 AGENTS.mdmanaged-only仅读取受管策略指令也可在 settings 中配置{ pluginConfigs: { agents-mdbuiltin: { options: { instructionFiles: claude-md-and-agents-md } } } }直接读取不可用的场景低于 v2.1.277 的版本、Bedrock/Vertex/Foundry、遥测被禁用、升级后的首次会话、disableAllHooks/allowManagedHooksOnly生效、或内置agents-md插件被禁用时Claude Code 不会自动拾取 AGENTS.md。此时需回退为从 CLAUDE.md 导入AGENTS.md或使用符号链接将CLAUDE.md指向它。需要澄清的定位AGENTS.md 是跨工具的项目上下文文件——与 CLAUDE.md 同属一个文档类别而非 agent 定义格式。它的存在让多个编码 Agent 共享同一套项目约定构建/测试/lint 命令、代码风格与架构约定、仓库布局。而子代理应定义在.claude/agents/*.md不是AGENTS.md 里。AGENTS.md 写作沿用相同原则聚焦精炼、渐进式披露、引用外部文档而非内嵌内容。实战要点与写作心法Skill 在 Notes 一节给出的经验总结值得全文背诵先验证命令可用再写入文件——CLAUDE.md 里出现失效命令会持续误导每个会话拿不准就删掉When in doubt, leave it out——系统提示会告诉 Claude CLAUDE.md 可能相关也可能不相关噪音越多被忽略得越厉害Monorepo 受益于清晰的 WHAT/WHY/HOW 结构目录级 CLAUDE.md 应更加聚焦。结合 claude-howto 自身实践还可补充几条可复用的写作心法用表格收纳高频命令参考 project-CLAUDE.md 的 Common Commands 表把 install/test/build/lint/migrate 等命令整理成命令—用途两列表格比零散段落更易被 Agent 定位给硬性规则单独成节仓库根 CLAUDE.md 的 Hard rules 一节集中列出 MUST NOT / MUST 条款如禁止未经明确要求提交推送、代码围栏必须声明语言等这类高影响力约定值得显式强调声明信息而非提醒只写 Agent 无法从代码推断的非显而易见事实架构取舍、环境前提不要写记得检查式的督促语。使用与安装在 claude-howto 仓库中claude-md Skill 的完整定义位于 03-skills/claude-md/SKILL.md仓库的 INDEX.md 将其归类为管理并优化 CLAUDE.md 文件的 Skill安装路径为个人级~/.claude/skills/或项目级.claude/skills/# 项目级安装团队共享提交到 git mkdir -p .claude/skills/claude-md cp 03-skills/claude-md/SKILL.md .claude/skills/claude-md/ # 个人级安装跨项目可用 mkdir -p ~/.claude/skills/claude-md cp 03-skills/claude-md/SKILL.md ~/.claude/skills/claude-md/安装后在会话中直接调用/claude-md create触发创建流程或让描述中的关键词CLAUDE.md、project documentation、AI onboarding自动激活该 Skill。编辑 Skill 文件后运行/reload-skillsv2.1.152即可重新扫描技能目录无需重启会话。快速落地路径先用/claude-md create生成初稿再对照验收清单逐项自查对已有项目用/claude-md audit定位反模式用/claude-md update精准瘦身复杂项目从第一步就引入agent_docs/渐进式披露结构。配合 02-memory/README.md 中/init初始化、/memory维护、导入与200 行以内的量化标准即可把 CLAUDE.md 从越写越臃肿的说明书变成每个会话都高效起效的 Agent 接入文档。本文基于 claude-howto 仓库 03-skills/claude-md/SKILL.mdSkill 定义标注 Claude Code v2.1.278撰写相关佐证包括 03-skills/README.mdSkill 加载机制、02-memory/README.md内存层级与 CLAUDE.md 精简原则及仓库内三个可直接复用的 CLAUDE.md 模板。赞分享教程文档【免费下载链接】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-md Skill 创建、更新与审计 CLAUDE.md为 AI Agent 打造高效的 Onboarding 文档claude howto 实战用 claude md Skill 创建、更新与审计 CLAUDE.md为 AI Agent 打造高效的 Onboarding教程文档Claude Code 个人记忆实战以 claude-howto 仓库的 personal-CLAUDE.md 为模板编写专属 ~/.claude/CLAUDE.mdClaude Code 个人记忆实战以 claude howto 仓库的 personal CLAUDE.md 为模板编写专属 ~/.claude/CLAU教程文档用 claude-md-improver 技能审计并改进 CLAUDE.md为 Claude Code 构建高质量项目记忆用 claude md improver 技能审计并改进 CLAUDE.md为 Claude Code 构建高质量项目记忆 CLAUDE.md 是 ClaudAI 插件开发工具插件系统上一篇Tether滚动优化提升长页面中的定位性能下一篇Pi0 VLA 模型昇腾 310P 的 ONNX/OM 两段式转换与推理排错实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/10 1:45:47 · 阅读 1.2k claude-howto 实战指南：用 claude-md Skill 编写高质量 CLAUDE.md，打通 AI Agent 的项目接入
教程文档【免费下载链接】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.md 是 Claude Code 会话中唯一被自动注入的项目上下文文件它的质量直接决定 AI Agent 对代码库的理解深度与协作效率。本文以 claude-howto 仓库中的claude-mdSkill03-skills/claude-md/SKILL.md为骨架系统讲解如何以create、update、audit三种模式创建、优化与审计 CLAUDE.md并借助本仓库的记忆体系02-memory/README.md与真实模板文件让你读完即可上手写出少而精、全会话通用、渐进式披露的项目接入文档。什么是 claude-md Skillclaude-md是一个文件系统型 Agent Skill其职责在 frontmatter 中定义得非常明确--- name: claude-md description: Create or update CLAUDE.md files following best practices for optimal AI agent onboarding ---它的核心使命是按照最佳实践创建或更新 CLAUDE.md 文件实现最优的 AI Agent 项目接入onboarding。在 claude-howto 仓库的 Skills 体系中它与 blog-draft、code-review-specialist、refactor 等 Skill 并列存放在03-skills/目录下属于参考型 任务型混合 Skill既注入项目文档写作的领域知识也提供create/update/audit三种明确的可执行任务流程。与一次性 Prompt 不同Skill 采用渐进式披露Progressive Disclosure加载元数据name description在会话启动时即被载入约 100 tokensSKILL.md 正文在被触发时才加载控制在 5k tokens 以内配套资源按需加载、规模近乎无上限。这意味着把 claude-md 安装进~/.claude/skills/或项目.claude/skills/后平时几乎不占上下文只有当用户提到 CLAUDE.md、项目文档或 AI 接入相关话题时才被激活。关于 Skill 的加载机制与安装路径可进一步参阅 03-skills/README.md。用户输入模式Skill 通过$ARGUMENTS接收用户输入并根据内容分流到三种模式参数行为create从零创建新的 CLAUDE.mdupdate改进已有的 CLAUDE.mdaudit分析并报告当前 CLAUDE.md 的质量具体路径如src/api/CLAUDE.md在指定目录创建/更新目录级 CLAUDE.md调用示例/claude-md create # 为当前项目新建 CLAUDE.md /claude-md update # 优化现有 CLAUDE.md /claude-md audit # 输出质量审计报告 /claude-md src/api/CLAUDE.md # 为 src/api 目录生成专属说明如果$ARGUMENTS为空Skill 按默认的create流程执行。核心原则CLAUDE.md 为何必须少而精Skill 开篇即点明一个关键事实LLM 是无状态的stateless。CLAUDE.md 是唯一一份会被自动纳入每次对话的文件它是 AI Agent 了解代码库的第一入口也是唯一入口。因此它承载的是每一次会话都必然相关的信息而非某一任务的临时说明。四条黄金法则The Golden Rules少即是多Less is More前沿 LLM 大约能遵循 150200 条指令而 Claude Code 的系统提示词本身已占用约 50 条。留给你的 CLAUDE.md 的空间极其有限必须聚焦、精炼。全会话通用Universal Applicability只收录与每一次会话都相关的信息。任务专属指令应拆分到独立文件中如 Skill、.claude/rules/*.md而不是塞进 CLAUDE.md。别把 Claude 当 Linter 用Dont Use Claude as a Linter代码风格规范会膨胀上下文并削弱指令遵循能力。格式与风格问题应交给确定性工具prettier、eslint 等解决Claude 只负责业务逻辑层面的判断。绝不自动生成Never Auto-GenerateCLAUDE.md 是整个 AI 工作流中杠杆率最高的文件必须由人手工精心撰写而不是让工具批量生成模板。仓库层面同样印证了这条原则——claude-howto 根目录的 CLAUDE.md 仅 60 余行却完整覆盖了仓库类型说明、关键命令、架构地图、硬性规则、工作流偏好与 token 效率约定是一个贴近实战的少而精范例。精简度与遵循度的实证依据02-memory/README.md 给出了更具体的量化结论Keeping CLAUDE.md Small一节经验法则CLAUDE.md 控制在 200 行以内。超过后文件仍会全量加载但指令遵循度随体积增长而下降。每一行都会在每一次会话中与无关任务争夺注意力所以把一切写进 CLAUDE.md是错误方向。当文件开始膨胀时正确的做法是把内容搬出去而不是删减措辞内容类型应该放哪原因多步骤流程Skill 目录按需加载只在相关时出现目录/文件类型专属规则.claude/rules/*.md带paths:frontmatter按 glob 限定作用域触碰匹配文件时才加载参考资料与长示例Skill 的references/目录仅在 Skill 需要时读取关于你的记忆Auto memory默认开启由 Claude 自动写入与加载需要注意一个常见误区path导入可以组织大型 CLAUDE.md但不能节省上下文——被导入文件在加载时同样会被完整拉入。真正能减少加载量的是把内容拆进按路径作用域生效的 rules 文件。此外v2.1.206 的/doctor命令会在 CLAUDE.md 膨胀到失去实用性时介入检查并提出精简建议。针对 Opus 5 / Fable 5 的特别提醒旧式指南常鼓励在 CLAUDE.md 里写做完必须跑测试务必复查工作之类的验证提醒。在 Claude Opus 5 和 Fable 5 上这类语句会引发过度验证——Claude 反复重查已经正确的工作白白消耗轮次与 token。应删除这类提醒改为陈述目标并让 Claude 自行判断真正非显而易见的需求如集成测试需要先启动 Docker属于信息而非提醒应当保留。执行流程从项目分析到文件落盘Skill 将 CLAUDE.md 的产出过程拆成七个阶段每个阶段都有明确的动作清单。阶段 1项目分析Project Analysis动手写作前先摸清项目现状检查已存在的 CLAUDE.md 文件根级./CLAUDE.md或.claude/CLAUDE.md目录级**/CLAUDE.md全局用户配置~/.claude/CLAUDE.md识别项目结构技术栈语言、框架、项目类型monorepo、单体应用、库、开发工具包管理器、构建系统、测试运行器。审阅现有文档README.md、CONTRIBUTING.md、package.json、pyproject.toml、Cargo.toml等。这一步决定了 CLAUDE.md 的既有事实避免重复收录 README 或包清单中已有的信息。阶段 2内容策略——WHAT / WHY / HOW 三维框架Skill 建议围绕三个维度组织 CLAUDE.md 内容这套框架尤其适合 monorepo 与复杂项目WHAT技术与结构技术栈总览、项目组织方式monorepo 尤其重要、关键目录及其用途。WHY目的与上下文项目做什么、某些架构决策为何如此、每个主要组件的职责。HOW工作流与约定开发工作流bunvsnode、pipvsuv等、测试流程与命令、验证与构建方法、关键陷阱gotchas与非显而易见的硬性要求。阶段 3渐进式披露策略Progressive Disclosure大型项目建议创建agent_docs/目录把细节沉淀为独立文件agent_docs/ |- building_the_project.md |- running_tests.md |- code_conventions.md |- architecture_decisions.md然后在 CLAUDE.md 中只引用这些文件For detailed build instructions, refer to agent_docs/building_the_project.md关键技巧使用file:line引用代替代码片段避免上下文过期——代码会被改而文件定位引用会始终指向最新内容。阶段 4质量约束Quality Constraints创建或更新 CLAUDE.md 时必须遵守五条约束目标长度控制在几百行以内越短越好无风格规则删除一切 lint / formatting 类指令无任务专属指令迁移到独立文件无代码片段改用文件引用无冗余信息不重复 package.json 或 README 里已有的内容。阶段 5必备章节模板Essential SectionsSkill 给出了可直接套用的骨架# Project Name Brief one-line description. ## Tech Stack - Primary language and version - Key frameworks/libraries - Database/storage (if any) ## Project Structure [Only for monorepos or complex structures] - apps/ - Application entry points - packages/ - Shared libraries ## Development Commands - Install: command - Test: command - Build: command ## Critical Conventions [Only non-obvious, high-impact conventions] - Convention 1 with brief explanation - Convention 2 with brief explanation ## Known Issues / Gotchas [Things that consistently trip up developers] - Issue 1 - Issue 2仓库中的 project-CLAUDE.md 正是这一模板的完整落地包含 Project Overview名称、技术栈、团队规模、Architecture用docs/architecture.md等导入、Development Standards代码风格、命名、Git 工作流、测试、API、数据库、部署、Common Commands 表格、Team Contacts、Known Issues Workarounds、Related Projects——可复制到自己的项目根目录直接改写使用。个人偏好则可参考 personal-CLAUDE.md目录级规则参考 directory-api-CLAUDE.md。阶段 6必须避开的反模式Anti-Patterns不要在 CLAUDE.md 中包含代码风格指南交给 linter如何使用 Claude 的说明文档对显而易见模式的长篇解释复制粘贴的代码示例通用最佳实践口号如写好代码特定任务的指令自动生成的内容冗长的 TODO 列表。阶段 7验收清单Validation Checklist落盘前逐项核验控制在几百行以内越短越好每一行都适用于所有会话无风格 / 格式化规则无代码片段改用文件引用所有命令都验证过可用复杂项目使用了渐进式披露关键陷阱gotchas已记录与 README.md 无冗余。三种模式的输出流程Skill 对create、update、audit三种模式给出了不同的工作流核心差异在于改与不改create或默认分析项目按上述结构起草 CLAUDE.md将草稿提交用户审阅获得批准后写入合适的位置。update读取现有 CLAUDE.md对照最佳实践审计识别三类变更需删除风格规则、代码片段、任务专属内容需压缩冗余或冗长的段落需补充缺失的必备信息提交变更方案供审阅批准后应用变更。audit读取现有 CLAUDE.md生成报告包含当前行数 vs 目标行数全会话通用内容占比百分比发现的反模式清单改进建议只报告、不修改文件。注意 update 与 audit 的边界update 会动手改文件audit 只输出诊断报告。在不确定时优先 audit把改动决定权留给用户。内存层级CLAUDE.md 在系统中的位置要写出合格的 CLAUDE.md还需理解它在 Claude Code 内存体系中的层级。据 02-memory/README.mdCLAUDE.md 文件按作用域从宽到窄存在多个位置按加载顺序排列注意这些文件是拼接进上下文而非互相覆盖作用域位置用途Managed policy受管策略macOS/Library/Application Support/ClaudeCode/CLAUDE.mdLinux/WSL/etc/claude-code/CLAUDE.mdWindowsC:\Program Files\ClaudeCode\CLAUDE.md组织级指令无法被个人设置排除User instructions用户指令~/.claude/CLAUDE.md跨项目的个人偏好Project instructions项目指令./CLAUDE.md或./.claude/CLAUDE.md团队共享、纳入版本控制Local instructions本地指令./CLAUDE.local.md个人项目专属偏好建议加入.gitignore目录树内的发现机制Claude Code 从工作目录向上遍历foo/CLAUDE.md先于foo/bar/CLAUDE.md加载——离启动目录更近的指令在上下文中出现得更晚更近于上下文末尾而非更高优先级。工作目录之下子目录里的 CLAUDE.md 则按需加载当 Claude 读取该子目录文件时才载入。子代理Subagent的内存作用域可通过定义文件中的memoryfrontmatter 限定memory: user # 仅加载用户级内存 memory: project # 仅加载项目级内存 memory: local # 仅加载本地内存目录级 CLAUDE.md 应比根级更聚焦。以 directory-api-CLAUDE.md 为例它开头就声明本文件是对根级 CLAUDE.md 在/src/api/下的补充内存文件是拼接而非覆盖Claude Code 在读取该子树文件时按需加载本文件随后只讲 API 模块专属的请求校验、鉴权、响应格式、分页、限流与缓存规范——这正是Universal Applicability原则在目录层级的应用。 导入语法避免重复、引用既有文档CLAUDE.md 支持path/to/file语法引入外部内容避免复制粘贴造成的维护漂移# Project Documentation See README.md for project overview See package.json for available npm commands See docs/architecture.md for system design # 使用绝对路径导入主目录文件 ~/.claude/my-project-instructions.md导入特性要点详见 02-memory/README.md相对路径与绝对路径均支持相对路径以包含该导入的文件所在位置为基准解析递归导入支持最大深度4 跳首次从外部位置导入会触发审批对话框安全机制导入指令在 markdown 代码跨段或代码块内不生效因此在示例中书写它们是安全的被引用内容会自动纳入 Claude 的上下文。AGENTS.md 处理跨工具项目上下文文件Skill 专门处理了 AGENTS.md 场景。自 v2.1.277 起Claude Code 将AGENTS.md直接作为项目指令读取——但仅当工作目录及其上每一级目录都不存在CLAUDE.md、.claude/CLAUDE.md或CLAUDE.local.md时。~/.claude/CLAUDE.md、受管 CLAUDE.md 和.claude/rules/不计入该检查会与胜出的项目文件一并继续加载。读取行为由/config中的Project instructions设置控制四个取值取值效果claude-md-or-agents-md默认——仅在找不到 CLAUDE.md 文件时读取 AGENTS.mdclaude-md-and-agents-md两者同时存在时都读取claude-md只读 CLAUDE.md 文件忽略 AGENTS.mdmanaged-only仅读取受管策略指令也可在 settings 中配置{ pluginConfigs: { agents-mdbuiltin: { options: { instructionFiles: claude-md-and-agents-md } } } }直接读取不可用的场景低于 v2.1.277 的版本、Bedrock/Vertex/Foundry、遥测被禁用、升级后的首次会话、disableAllHooks/allowManagedHooksOnly生效、或内置agents-md插件被禁用时Claude Code 不会自动拾取 AGENTS.md。此时需回退为从 CLAUDE.md 导入AGENTS.md或使用符号链接将CLAUDE.md指向它。需要澄清的定位AGENTS.md 是跨工具的项目上下文文件——与 CLAUDE.md 同属一个文档类别而非 agent 定义格式。它的存在让多个编码 Agent 共享同一套项目约定构建/测试/lint 命令、代码风格与架构约定、仓库布局。而子代理应定义在.claude/agents/*.md不是AGENTS.md 里。AGENTS.md 写作沿用相同原则聚焦精炼、渐进式披露、引用外部文档而非内嵌内容。实战要点与写作心法Skill 在 Notes 一节给出的经验总结值得全文背诵先验证命令可用再写入文件——CLAUDE.md 里出现失效命令会持续误导每个会话拿不准就删掉When in doubt, leave it out——系统提示会告诉 Claude CLAUDE.md 可能相关也可能不相关噪音越多被忽略得越厉害Monorepo 受益于清晰的 WHAT/WHY/HOW 结构目录级 CLAUDE.md 应更加聚焦。结合 claude-howto 自身实践还可补充几条可复用的写作心法用表格收纳高频命令参考 project-CLAUDE.md 的 Common Commands 表把 install/test/build/lint/migrate 等命令整理成命令—用途两列表格比零散段落更易被 Agent 定位给硬性规则单独成节仓库根 CLAUDE.md 的 Hard rules 一节集中列出 MUST NOT / MUST 条款如禁止未经明确要求提交推送、代码围栏必须声明语言等这类高影响力约定值得显式强调声明信息而非提醒只写 Agent 无法从代码推断的非显而易见事实架构取舍、环境前提不要写记得检查式的督促语。使用与安装在 claude-howto 仓库中claude-md Skill 的完整定义位于 03-skills/claude-md/SKILL.md仓库的 INDEX.md 将其归类为管理并优化 CLAUDE.md 文件的 Skill安装路径为个人级~/.claude/skills/或项目级.claude/skills/# 项目级安装团队共享提交到 git mkdir -p .claude/skills/claude-md cp 03-skills/claude-md/SKILL.md .claude/skills/claude-md/ # 个人级安装跨项目可用 mkdir -p ~/.claude/skills/claude-md cp 03-skills/claude-md/SKILL.md ~/.claude/skills/claude-md/安装后在会话中直接调用/claude-md create触发创建流程或让描述中的关键词CLAUDE.md、project documentation、AI onboarding自动激活该 Skill。编辑 Skill 文件后运行/reload-skillsv2.1.152即可重新扫描技能目录无需重启会话。快速落地路径先用/claude-md create生成初稿再对照验收清单逐项自查对已有项目用/claude-md audit定位反模式用/claude-md update精准瘦身复杂项目从第一步就引入agent_docs/渐进式披露结构。配合 02-memory/README.md 中/init初始化、/memory维护、导入与200 行以内的量化标准即可把 CLAUDE.md 从越写越臃肿的说明书变成每个会话都高效起效的 Agent 接入文档。本文基于 claude-howto 仓库 03-skills/claude-md/SKILL.mdSkill 定义标注 Claude Code v2.1.278撰写相关佐证包括 03-skills/README.mdSkill 加载机制、02-memory/README.md内存层级与 CLAUDE.md 精简原则及仓库内三个可直接复用的 CLAUDE.md 模板。赞分享教程文档【免费下载链接】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-md Skill 创建、更新与审计 CLAUDE.md为 AI Agent 打造高效的 Onboarding 文档claude howto 实战用 claude md Skill 创建、更新与审计 CLAUDE.md为 AI Agent 打造高效的 Onboarding教程文档Claude Code 个人记忆实战以 claude-howto 仓库的 personal-CLAUDE.md 为模板编写专属 ~/.claude/CLAUDE.mdClaude Code 个人记忆实战以 claude howto 仓库的 personal CLAUDE.md 为模板编写专属 ~/.claude/CLAU教程文档用 claude-md-improver 技能审计并改进 CLAUDE.md为 Claude Code 构建高质量项目记忆用 claude md improver 技能审计并改进 CLAUDE.md为 Claude Code 构建高质量项目记忆 CLAUDE.md 是 ClaudAI 插件开发工具插件系统上一篇Tether滚动优化提升长页面中的定位性能下一篇Pi0 VLA 模型昇腾 310P 的 ONNX/OM 两段式转换与推理排错实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考