get-shit-done 的 CLAUDE.md 模板解析：7 分区标记驱动的 Claude Code 项目上下文自动生成机制-迪斯科星球

get-shit-done 的 CLAUDE.md 模板解析：7 分区标记驱动的 Claude Code 项目上下文自动生成机制

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done

在 Claude Code 项目中，CLAUDE.md是 Claude 每次会话启动时读取的项目级指令文件，它的质量直接决定 Agent 对项目身份、技术栈、代码约定、架构与工作流的理解程度。get-shit-done（GSD）为此提供了一套可自动生成、可分区独立更新、可回退降级的CLAUDE.md模板，由gsd-tools generate-claude-md子命令驱动。本文以 get-shit-done/templates/claude-md.md 为骨架，结合 sdk/src/query/profile-output.ts 的底层实现，完整讲解模板的 7 个标记分区、fallback 行为、marker 更新协议，以及如何把分散在.planning/下的规划产物（PROJECT、STACK、CONVENTIONS、ARCHITECTURE）与各目录下的 Skills 汇总成一份可被 Claude 直接消费的单一上下文文件。读完本文，你将理解 GSD 如何让 CLAUDE.md 的维护从"手工手写、极易漂移"升级为"源文件驱动、分区精准更新"。

模板定位：由`generate-claude-md`管理的项目根 CLAUDE.md

模板的头部明确交代了它的用途与职责边界：

它是项目根目录CLAUDE.md的模板，由gsd-tools generate-claude-md自动生成；
全文由7 个 marker 界定（marker-bounded）的分区构成，每个分区都可以独立更新；
其中6 个分区（project、stack、conventions、architecture、skills、workflow enforcement）由generate-claude-md子命令管理；
Profile（开发者画像）分区由generate-claude-profile独占管理，generate-claude-md只在新建文件时写入占位符。

这一分工在源码中得到精确印证：generateClaudeMd的MANAGED_SECTIONS常量仅包含六个分区（profile-output.ts），而CLAUDE_MD_PROFILE_PLACEHOLDER占位符块与 profile 的实际写入逻辑（含--global、--refresh、目标路径解析）则属于generate-claude-profile的职责（profile-output.ts）。这意味着两份生成器可以在同一文件中"分域而治"，互不覆盖。

七个分区模板全解

以下每个分区都遵循统一的骨架：HTML 风格注释标记起始、##二级标题、内容主体、结束标记。模板中所有分区原文如下，均为可直接复制使用的形式。

Project 分区（项目身份）

<!-- GSD:project-start source:PROJECT.md --> ## Project {{project_content}} <!-- GSD:project-end -->

Fallback 文本：

Project not yet initialized. Run /gsd:new-project to set up.

当.planning/PROJECT.md缺失或尚未初始化时，Claude 会得到明确的行动指引——先运行/gsd:new-project建立项目，而不是面对一条"信息缺失"的空白提示。

源码中generateProjectSection的实现（profile-output.ts）说明该分区并非简单整段搬运 PROJECT.md，而是做了结构化抽取：读取#一级标题作为加粗项目名，依次提取What This Is、Core Value、Constraints三个小节重组为紧凑的项目画像；若提取结果为空，则回退到 fallback 文本。

Stack 分区（技术栈）

<!-- GSD:stack-start source:STACK.md --> ## Technology Stack {{stack_content}} <!-- GSD:stack-end -->

Fallback 文本：

Technology stack not yet documented. Will populate after codebase mapping or first phase.

generateStackSection（profile-output.ts）按优先级读取两个来源：优先.planning/codebase/STACK.md，缺失时回退.planning/research/STACK.md，两者都缺才进入 fallback。内容生成时只保留表格行（|开头）、列表项（-/*开头）以及二级及以下标题，形成一个精简的技术栈摘要，避免把冗长的研究笔记灌进 CLAUDE.md。

Conventions 分区（代码约定）

<!-- GSD:conventions-start source:CONVENTIONS.md --> ## Conventions {{conventions_content}} <!-- GSD:conventions-end -->

Fallback 文本：

Conventions not yet established. Will populate as patterns emerge during development.

实现上generateConventionsSection（profile-output.ts）读取.planning/codebase/CONVENTIONS.md，同样只抽取列表项与表格行作为"约定速览"。fallback 语义是：约定会随开发过程自然沉淀，现在没有不等于禁止开发。

Architecture 分区（系统结构）

<!-- GSD:architecture-start source:ARCHITECTURE.md --> ## Architecture {{architecture_content}} <!-- GSD:architecture-end -->

Fallback 文本：

Architecture not yet mapped. Follow existing patterns found in the codebase.

generateArchitectureSection（profile-output.ts）读取.planning/codebase/ARCHITECTURE.md，抽取列表、表格与代码块，保留架构文档中最具信息量的结构化部分。fallback 给出了一个极其实用的行为指令：架构未绘制时，"遵循代码库中已有的模式"——这是把"未知"转化为可执行策略的典型写法。

Skills 分区（项目技能清单）

<!-- GSD:skills-start source:skills/ --> ## Project Skills | Skill | Description | Path | | -------------- | --------------------- | ------------------------- | | {{skill_name}} | {{skill_description}} | `{{skill_path}}/SKILL.md` | <!-- GSD:skills-end -->

Fallback 文本：

No project skills found. Add skills to any of: `.claude/skills/`, `.agents/skills/`, `.cursor/skills/`, or `.github/skills/` with a `SKILL.md` index file.

模板明确定义了技能的发现行为（Discovery behavior）：

依次扫描.claude/skills/、.agents/skills/、.cursor/skills/、.github/skills/下包含SKILL.md的子目录；
从 YAML frontmatter 中提取name和description（支持多行描述）；
跳过 GSD 自身安装的技能（目录以gsd-开头）；
跨目录按技能名去重。

源码将这一行为落实为SKILL_SEARCH_DIRS数组与generateSkillsSection（profile-output.ts）：逐目录枚举子目录，过滤gsd-前缀，读取SKILL.md的 frontmatter（extractSkillFrontmatter支持续行拼接待缩进的 description），按name去重后生成三列表格；同时把描述中的|转义为\|以防破坏 Markdown 表格结构。另外，源码中的搜索目录还包含.codex/skills/，与模板中的四目录清单相比覆盖面更广，实际生效范围以当前仓库实现为准。

Workflow Enforcement 分区（工作流强制）

<!-- GSD:workflow-start source:GSD defaults --> ## GSD Workflow Enforcement Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync. Use these entry points: - `/gsd:quick` for small fixes, doc updates, and ad-hoc tasks - `/gsd:debug` for investigation and bug fixing - `/gsd:execute-phase` for planned phase work Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it. <!-- GSD:workflow-end -->

这是模板中唯一不带 fallback 的分区：它由 GSD 默认值（source:GSD defaults）恒定生成，generateWorkflowSection在源码中直接返回常量CLAUDE_MD_WORKFLOW_ENFORCEMENT（profile-output.ts）。其核心主张是：任何文件修改类操作（Edit、Write 等）之前，都应先经由 GSD 命令进入工作流，确保规划产物与执行上下文保持同步；除非用户明确要求绕过，否则不要在工作流之外直接修改仓库。需要说明的是，当前源码常量中的命令形式为/gsd-quick、/gsd-debug、/gsd-execute-phase（连字符形式），模板文件中为/gsd:quick等冒号形式，具体以你所用 GSD 版本的命令清单为准。

Profile 分区（占位符，仅供外部管理）

<!-- GSD:profile-start --> ## Developer Profile > Profile not yet configured. Run `/gsd:profile-user` to generate your developer profile. > This section is managed by `generate-claude-profile` — do not edit manually. <!-- GSD:profile-end -->

模板特别强调：该分区不由generate-claude-md管理，而是由generate-claude-profile独占管理；上述占位符仅在新建 CLAUDE.md 且尚无 profile 分区时使用。源码中generateClaudeMd的更新循环对 profile 分区做了条件化处理：非--auto模式下，若文件中不存在<!-- GSD:profile-start标记则追加占位符，并在结果消息中提示"Run /gsd-profile-user to unlock Developer Profile"（profile-output.ts）；profile 的真实内容由cmdWriteProfileLogic写入，包含维度评分表（Dimension / Rating / Confidence）与行为指令（Directives），并支持--global写入~/.claude/CLAUDE.md（profile-output.ts）。

分区排序规则

模板定义了固定的 7 级顺序，每一级对应一个明确的信息学问题：

Project— 身份与目的（这个项目是什么）
Stack— 技术选型（使用了哪些工具）
Conventions— 代码模式与规则（代码怎么写）
Architecture— 系统结构（组件如何拼装）
Skills— 发现到的项目技能（具备哪些领域知识）
Workflow Enforcement— 文件变更工作的 GSD 默认入口
Profile— 开发者行为偏好（如何交互）

从源码结构看，这一顺序由sectionHeadings映射与MANAGED_SECTIONS的声明顺序共同保证（profile-output.ts）：新建文件时按序拼接六个分区并追加 profile 占位符（profile-output.ts）。排序逻辑是"从客观事实到主观偏好"：先讲清项目与技术，再讲约定与架构，最后才是交互偏好——确保 Claude 先建立事实基础，再获得行为约束。

Marker 格式与分区更新协议

所有分区的边界由统一格式的 HTML 注释标记界定，这是"分区独立更新"机制的基石：

起始标记：，其中source属性记录了该分区内容的来源文件；
结束标记：；
source属性使生成器能在源文件变化时进行定向更新；
起始标记采用不含闭合-->的部分匹配进行检测，容错性更强。

源码将这套协议实现为一组对称的原语（profile-output.ts）：

extractSectionContent：按起始/结束标记切出分区内部内容，起始标记按第一个-->之后取值；
buildSection：把分区名、来源文件与内容重组为完整标记块；
updateSection：若目标文件已存在该分区标记，则整体替换该块（action 为replaced）；否则追加到文件末尾（action 为appended）；
detectManualEdit：对比分区当前内容与期望内容（规范化空白后），判断该分区是否被用户手工改写过——这是--auto模式跳过人工编辑分区的依据。

Fallback 行为：缺数据时的"可行动指引"

模板在结尾总结了 fallback 的统一设计哲学，这也是该项目文档工程的核心准则之一：

当源文件缺失时，fallback 文本为 Claude 提供可执行的行动指引；
它不是占位广告，也不是简单的"缺失"通知；
每条 fallback 都告诉 Claude该做什么，而不只是报告什么不存在。

对照源码中的CLAUDE_MD_FALLBACKS常量（profile-output.ts）可以清楚看到这条准则的落地：project 的 fallback 指引运行/gsd:new-project；stack 说明"将在代码库映射或首个 phase 后填充"；conventions 说明"约定将在开发中随模式浮现"；architecture 指引"遵循代码库已有模式"；skills 则列举了四种技能目录的存放位置。每一条都以动词开头或包含明确动作，让 Claude 在信息真空时依然有路可走。

源码级流程：一次`generate-claude-md`的完整生命周期

综合 profile-output.ts 的实现，可以把整个生成流程还原为如下阶段：

参数解析：识别--output（自定义输出路径）与--auto（自动模式）两个标志；
逐分区生成：遍历MANAGED_SECTIONS六个分区，分别调用对应的生成器，同时统计sectionsGenerated（有真实来源）与sectionsFallback（走 fallback）；
解析输出路径：默认读取配置中的claude_md_path（缺省为./CLAUDE.md）；这里有一个值得注意的运行时适配——当检测到当前运行时是 Codex 时，输出目标会被强制改写为./AGENTS.md，确保 Codex 项目永远不会写入 CLAUDE.md（源码注释标注为 #3163，见 profile-output.ts）；
新建 vs 更新：
- 文件不存在：按排序拼接六个分区 + profile 占位符，action 为created；
- 文件已存在：逐分区按标记原位替换；在--auto模式下，detectManualEdit检测到某分区被手工改写过就跳过该分区（计入sectionsSkipped），保护用户的定制内容不被自动生成覆盖；
profile 占位符治理：非--auto模式下自动补齐缺失的 profile 占位符；
结果报告：返回claude_md_path、action、各分区的生成/回退/跳过清单与总分区数，并输出人类可读的消息，例如Generated 4/6 sections. Fallback: stack, skills. Run /gsd-profile-user to unlock Developer Profile.

这套流程的意义在于：CLAUDE.md 不再是一次性手写的静态文件，而是由.planning/下的真实规划产物（PROJECT.md、STACK.md、CONVENTIONS.md、ARCHITECTURE.md）和各 Skills 目录投影生成的动态上下文。规划文档更新后，重新运行生成命令即可让 CLAUDE.md 与之一致，从机制上杜绝"上下文漂移"。

延伸：模板在仓库中的位置与生态

claude-md.md存放在 GSD 的模板目录 get-shit-done/templates/，与 AI-SPEC、DEBUG、SECURITY、UAT、state 等模板并列，属于 GSD 模板体系中面向"Claude 运行时上下文"的一环；模板目录内的 README 对各类模板的用途有集中说明（get-shit-done/templates/README.md）。与之配套的完整命令生态包括：/gsd:new-project（初始化项目与 PROJECT.md）、/gsd:profile-user（生成 Developer Profile 分区）、/gsd:quick、/gsd:debug、/gsd:execute-phase（Workflow Enforcement 分区中列出的三个工作流入口），以及 map-codebase 等产生 STACK/CONVENTIONS/ARCHITECTURE 源文件的命令。要实际体验，只需在项目根目录运行gsd-tools generate-claude-md（可选--output指定路径、--auto启用跳过人工分区），并用gsd-tools generate-claude-profile解锁最后的 Profile 分区——一个包含项目画像、技术栈、约定、架构、技能清单、工作流约束与开发者偏好的完整项目上下文文件即告生成。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析