claude-skills Intake Phase 实战:为现有代码库建立基线理解的一次性准入流程

claude-skills Intake Phase 实战:为现有代码库建立基线理解的一次性准入流程 claude-skills Intake Phase 实战为现有代码库建立基线理解的一次性准入流程【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills本篇指南以 claude-skills 仓库工作流中的Intake Phase准入阶段为核心讲解如何在接手一个既有项目时通过三条链式命令完成代码库文档化、行为特征测试与系统描述生成为后续 Discovery、Planning、Execution 等所有阶段提供共享上下文。读完本文你将掌握 Intake 阶段三条命令intake:document-codebase、intake:capture-behavior、intake:create-system-description的调用方式、输入输出契约与真实实现见 docs/workflow/intake-phase.md、commands/intake/并能独立在你的项目中落地这一准入流程。Intake Phase 是什么一次运行、长期受益的项目 onboardingIntake Phase 是 claude-skills 工作流中的一次性项目准入阶段定义在 docs/workflow/intake-phase.md 中。它的定位非常明确One-time project onboarding that establishes baseline understanding of an existing codebase. Run once when first adopting a project; results feed every subsequent phase.也就是说它只在首次采用一个项目时运行一次作用是建立对现有代码库的基线理解并且它的产出会馈送到后续每一个阶段Discovery、Planning、Execution、Retrospectives。它不是持续运行的日常流程而是一劳永逸的基础设施建设——把团队对项目的理解沉淀为可复用的文档与测试资产。在 commands/workflow-manifest.yaml 中这一点体现得非常直接intake: description: docs/workflow/intake-phase.md depends_on: [] # 无前置依赖 run_once: true # 只运行一次 commands: - command: intake:document-codebase definition: commands/intake/document-codebase.yaml - command: intake:capture-behavior definition: commands/intake/capture-behavior.yaml - command: intake:create-system-description definition: commands/intake/create-system-description.yaml从这段清单可以看出 Intake 的三个关键特征无任何前置阶段依赖depends_on: []、全流程只执行一次run_once: true、按固定顺序执行三条命令。Purpose为什么在写任何功能前先做 Intake原文档对 Intake 的目的有精炼的阐述在任何特性工作开始之前团队需要三样东西——被文档化的代码、行为安全网和共享的系统概述。Before any feature work begins, the team needs documented code, behavioral safety nets, and a shared system overview.这三个需求的背后逻辑很实际文档化的代码接手旧项目时最大的痛点是看不懂。函数签名、模块职责、接口行为散落在代码里任何开发者或 Agent 都要靠追踪实现来理解。Intake 的第一步就把这些全部补齐。行为安全网旧代码往往没有测试改一处崩一片而无人察觉。Intake 的第二步通过特征测试characterization tests把当前行为固化成可回归验证的安全网。共享系统概述架构、API、安全模式、外部依赖需要一份人人可见的统一视图而不是散落在各人脑中的碎片知识。Intake 的第三步产出这份活文档。三者按顺序生产、层层递进先让代码可读文档再让行为可验证测试最后让系统可理解描述。三条命令总览Intake 阶段由三条命令按顺序组成来自 commands/workflow-manifest.yaml 的 phase 定义与 docs/workflow/intake-phase.md 的命令表顺序命令作用摘要1intake:document-codebase扫描并记录所有未文档化的函数、类、模块2intake:capture-behavior编写断言当前行为的特征测试3intake:create-system-description生成docs/system-description.md活文档三条命令的调用签名统一均可接受一个可选的directory参数默认为项目根目录。这一点在三份命令清单commands/intake/document-codebase.yaml、commands/intake/capture-behavior.yaml、commands/intake/create-system-description.yaml中保持一致argument-hint: [directory]repeat: false。命令一intake:document-codebase——补齐全代码库的文档缺口行为定义该命令的完整规格见 docs/workflow/intake-document-codebase.md。它扫描整个代码库找出所有缺少文档的函数、类、模块和端点并优先处理公共 API 与外部接口。在生成任何内容之前它会先呈现一份范围摘要供人类审批避免大面积改动前失去控制The agent scans the codebase, identifies every function, class, module, and endpoint that lacks documentation, and prioritizes public APIs and external-facing interfaces first. Before generating anything, it presents a scope summary for approval.审批通过后它会在整个代码库中生成docstrings / JSDoc / XML docs目标是一个可验证的效果任何开发者或 Agent 都能在不追踪实现的情况下仅凭函数签名与文档理解代码。输入输出契约依据 docs/workflow/intake-document-codebase.md 与其 YAML 清单 commands/intake/document-codebase.yaml方向名称类型必填说明输入directorystring否要扫描的根目录默认为项目根目录输出documentation-reportreport—文档添加摘要函数数、类数、模块数命令的 YAML 定义中requires: []表示它不依赖任何先决命令是整个 Intake 链的起点status: planned表示在当前仓库版本中该命令处于已规划状态尚未完全落地实现。执行要点先报范围、后动笔范围摘要审批机制让人类对将要改动哪些文件有知情权这在大型代码库中尤其重要。公共优先优先覆盖公共 API 和外部接口内部实现细节次之保证文档投入产出比。输出可量化最终的报告按函数、类、模块三类分别统计数量让文档覆盖度可度量、可追踪。下一步代码库文档化完成后紧接着运行intake:capture-behavior为这批新文档化的代码建立行为测试。命令二intake:capture-behavior——用特征测试固化现有行为行为定义完整规格见 docs/workflow/intake-capture-behavior.md。它扫描没有被测试覆盖的行为并编写**特征测试characterization tests**来断言当前功能将其作为未来变更的安全网。这里有一个至关重要的方法论区分The agent identifies functions, endpoints, and components with no test coverage and builds a test plan based on what the codecurrently does— not what it should do.特征测试断言的是代码当前实际做了什么而不是应该做什么。它的意义在于旧代码可能存在历史遗留行为甚至已知缺陷我们不去评判对错而是先把现状冻结下来。这样一来未来任何变更如果意外改动了这些行为测试会立即暴露回归。在提交之前这些测试会针对真实运行中的代码执行一遍确认通过后才落地——保证安全网本身是可用的。输入输出契约依据 docs/workflow/intake-capture-behavior.md 与其 YAML 清单 commands/intake/capture-behavior.yaml方向名称类型必填说明输入directorystring否扫描未测试行为的根目录默认为项目根目录输出characterization-testsfile—断言当前行为的测试文件输出coverage-reportreport—已捕获行为与新增覆盖的摘要与第一条命令不同该命令的requires: []虽然为空但其前置条件在文档层面有明确要求代码库已完成文档化来自intake:document-codebase且项目测试框架已配置并可直接运行——特征测试需要真实跑通所以可运行的测试环境是硬性前提。执行要点以现状为准测试描述代码现在这样工作而非代码应该这样工作这是特征测试与传统测试的本质区别。提交前必验证测试必须对真实代码运行并通过后才提交杜绝写出假绿的安全网。覆盖可汇报最终输出两份产物——测试文件本体 覆盖报告后者给出捕获了多少行为、增加了多少覆盖的量化结果。下一步行为捕获完成后运行intake:create-system-description生成系统级活文档。命令三intake:create-system-description——并行分析生成系统活文档行为定义完整规格见 docs/workflow/intake-create-system-description.md。这是 Intake 的收官命令它启动并行分析线程同时从多个维度解剖系统一个线程映射架构服务、数据库、队列另一个线程编目API 表面另一个线程追踪安全模式认证、加密、访问控制另一个线程映射外部依赖。最终产物写入docs/system-description.md其文档定位是适合审计员或新来的高级工程师阅读的系统概览SOC2 风格。这份文档会成为所有后续工作流阶段共享的上下文并且在工作流生命周期内持续演进执行期间增量更新回顾retrospective期间整体审查。输入输出契约依据 docs/workflow/intake-create-system-description.md 与其 YAML 清单 commands/intake/create-system-description.yaml方向名称类型必填路径说明输入directorystring否—要分析的根目录默认为项目根目录输出system-descriptionfile—docs/system-description.md活文档架构、API 表面、安全、部署、第三方依赖这是三条命令中唯一在 YAML 清单里显式给出输出路径的path: docs/system-description.md说明它是 Intake 阶段的核心交付物。执行要点并行而非串行架构、API、安全、依赖四个维度互不阻塞并行线程显著缩短分析时间。读者导向目标是审计员或新高级工程师这类零背景读者文档必须自包含、可独立理解。活的文档它不是一次性的交付物而是后续阶段持续更新的基线——执行时增量修订回顾时整体审查。前置条件该命令的前置条件完整继承了前两条命令的产出见 docs/workflow/intake-create-system-description.md代码库已完成文档化来自intake:document-codebase特征测试已就位来自intake:capture-behavior。Prerequisites运行 Intake 前需要准备什么原文档明确列出了 Intake 阶段的前置条件门槛非常低项目代码库访问权限——这是唯一硬性要求无需任何外部工具——不依赖工单系统如 Jira或文档系统如 Confluence。这一点与后续阶段形成鲜明对比例如 docs/workflow/discovery-phase.md 需要工单系统与文档系统访问权限而 Intake 完全可以在纯本地代码库上离线完成适合作为任何项目工作流的起点。结合 docs/workflow/intake-capture-behavior.md 的补充说明可以推断如果项目测试框架尚未配置至少需要先让它可运行因为特征测试需要真实执行验证。产出物Intake 交付的三类资产原文档将 Intake 的产出总结为三类资产这也是后续所有阶段共享的基础产出物内容核心价值文档化代码库每个公共 API 和模块上的 Docstrings/JSDoc/XML 文档任何人无需追踪实现即可理解函数签名与模块职责特征测试断言当前行为的测试文件检测非预期行为变更的安全网防回归系统描述docs/system-description.md架构概述、API 表面、安全模式、外部依赖供审计员或新工程师阅读的共享系统视图三者分别对应 Purpose 中提到的documented code、behavioral safety nets、shared system overview形成一条完整的可读 → 可验证 → 可理解链路。在工作流中的位置Intake 之后去哪下游分叉Discovery 还是直接 PlanningIntake 完成后后续走向由是否需要 Discovery 决定见 docs/workflow/intake-phase.md 的 Next Steps需要 Discovery系统描述会先供feature-forge在特性定义阶段读取当它识别出存在无法从现有知识回答的未知项如需要用户访谈、竞品分析、技术探针时进入 Discovery Phase通过discovery:create→discovery:synthesize→discovery:approve三条命令完成研究、综合与决策不需要 Discovery直接跳到 Planning Phase通过planning:epic-plan生成干系人可读的概览文档再用planning:impl-plan转换为可独立领取执行的实施计划。依赖强度intake 到 discovery 只是推荐值得注意的细节来自 commands/workflow-manifest.yamlDiscovery 对 Intake 的依赖强度是recommended推荐而非required且 Discovery 本身是optional: true可选阶段。也就是说如果项目足够简单、特性足够明确完全可以跳过 Discovery但无论走哪条路Intake 的产出——尤其是docs/system-description.md——都是 Planning 和 Execution 阶段理解代码库的共享上下文基础。系统描述的后续生命周期按 docs/workflow/intake-create-system-description.md 的说明docs/system-description.md在 Intake 之外仍有明确的生命周期管理执行阶段增量更新回顾阶段整体审查。它不是一个写完就归档的静态文档而是贯穿整个项目生命周期的活基线。这也是run once, feed every subsequent phase这句话的真正含义——Intake 只运行一次但它的影响力持续到项目的每次迭代。落地实践建议综合原文档与仓库中的命令清单这里给出将 Intake 应用于实际项目的操作建议按顺序严格执行三条命令存在产出依赖文档 → 测试 → 描述不要跳过或重排。工作流清单中它们在同一 phase 内按序声明。善用directory参数默认扫描项目根目录但对超大单体仓库可以分批对子模块执行或先用范围审批确认改动边界。把特征测试当作真相快照捕获行为时不要顺手修正旧逻辑——那是后续功能开发阶段的事Intake 阶段的目标是冻结现状。让系统描述保持更新执行阶段每次改动都增量更新docs/system-description.md回顾阶段做整体一致性审查避免它沦为过期文档。结合仓库内参考资源claude-skills 的 commands/common-ground/ 提供团队工作时的共同约定参考特性定义阶段可参考 skills/feature-forge/SKILL.md 的读取方式理解系统描述如何被下游消费。总结Intake Phase 是 claude-skills 工作流的第一个阶段也是唯一一个run_once的阶段它在项目首次被采用时通过intake:document-codebase文档化代码库、intake:capture-behavior特征测试安全网、intake:create-system-description系统活文档三条链式命令建立可读、可验证、可理解的基线资产。这些资产随后被feature-forge、Discovery、Planning、Execution 与 Retrospectives 各阶段持续消费与更新——一次准入投入换取整个项目生命周期的理解上下文。【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考