学习指南: 第5部分. 项目初始设置

模块「第5部分. 项目初始设置」中第 3 / 5 节课

您正在未登录状态下查看课程。请登录，以保存进度并参加测试。

主题：第5部分. 项目初始设置

难度等级：中级

预计学习时间：1.5–2 小时

先决条件：对 dbt 及模型分层（staging、intermediate、marts）有基本了解

熟悉 AI 智能体作为开发参与者的概念

理解版本控制（Git）原理及仓库操作

具有关系型数据仓库和 SQL 使用经验

了解什么是模型规范与数据集市契约

学习目标：解释为什么在数据项目中初始设置比在普通应用中更重要

按照课程标准创建最小化的项目目录结构

在 AGENTS.md 中撰写五条简短的智能体行为规则

区分 AGENTS.md 和 specs/tech-stack.md 的职责范围

根据工件和验证证据编制项目路线图

起草一个用于审计项目骨架（且不修改文件）的 Qwen 查询

用「在 /clear 之后，新智能体无需复述聊天内容即可理解项目」这一标准来验证项目设置

概述：本章描述了在 AI 智能体与人类作为搭档协作的数据项目中，最小但必备的初始设置。设置的目标是将决策记忆从聊天窗口转移到仓库文件：使命、技术栈、路线图、模型规范、验证笔记和评审报告。本章讨论为什么需要 specs/、models/ 和 tests/ 目录，AGENTS.md 中应该写什么，按层级划分的路线图有何缺陷，以及使用何种查询来委托智能体审计项目骨架。本章结束后，仓库中应存在 AGENTS.md、specs/mission.md、specs/tech-stack.md、specs/roadmap.md、用于模型规范的目录、用于验证笔记和评审报告的目录，以及 dbt 项目的骨架。本章教授一个核心原则：在设置阶段，创建的不是现成的工件，而是这些工件将要存放的「位置」。设置完成的标志不是文件夹被创建出来，而是这些文件夹开始承载决策。

核心概念：项目记忆 vs 聊天记忆：项目记忆是文件夹结构和文件（mission.md、tech-stack.md、roadmap.md、模型规范、验证笔记、评审报告）。聊天记忆是与智能体的对话内容，在第一次 /clear 时消失。在上下文重置之前，聊天记忆看起来很方便，但对下一位接手的同事和下一位评审者来说毫无用处。初始设置的目的在于让决策存在于文件中，而不是对话框中。

最小化的目录结构：标准仓库布局为：specs/（包含 mission.md、tech-stack.md、roadmap.md 文件以及 models/、validation/、reviewer-reports/ 子目录），models/（包含 staging/、intermediate/、marts/ 子目录），tests/，AGENTS.md，dbt_project.yml，profiles.yml。在设置阶段，需要的不是已准备好投入生产环境的工件，而是决策将要存放的「位置」。例如，如果没有 specs/validation/ 文件夹，验证证据几乎必然会留在聊天记录或 PR 描述中。

AGENTS.md 作为行为文件：这是一个简短的文件，用于在智能体进行修改前规定其行为：需要阅读什么（mission、tech-stack、roadmap、相关规范），不能做什么（不暴露直接的 PII、不擅自修改 grain、SLA 和契约字段），需要运行哪些检查（dbt build），如何汇报（基于验证证据而非承诺）。AGENTS.md 不是百科全书，而是行为规则列表。规则越简短，智能体和人使用它的可能性就越高。

AGENTS.md 与 specs 的划分：AGENTS.md 描述智能体应如何行为。specs/mission.md 描述项目的目的。specs/tech-stack.md 描述允许使用的技术栈及其原因。specs/roadmap.md 描述应出现哪些工件。specs/models/ 存放模型契约。specs/validation/ 存放验证笔记。specs/reviewer-reports/ 存放评审报告。产品承诺、契约字段和验收证据应放在 specs/ 中，而不是 AGENTS.md 中。

按工件划分的路线图：在数据项目中，路线图最好按证据而非层级来组织。糟糕的表述示例：「已编写模型 marts/customer_360.sql」。良好的表述示例：「Customer 360 数据集市已通过评审者验证」。这样就能看出「模型已编写」并不等于「产品已就绪」。本章中的具体示例：1) raw/staging 可复现；2) Customer 360 契约已批准；3) Customer 360 数据集市已通过验证；4) 风险、信贷和同意书的数据集市已通过评审者验证；5) 实践考核的发布证据已就绪。

意义、验证与评审的分层：specs/models/、specs/validation/ 和 specs/reviewer-reports/ 这三个目录向智能体表明，意义、验证和评审是独立的分层，而不是 SQL 的附言。如果这些目录不存在，真相之源就会出现在对智能体而言最方便的地方：注释、命令输出、回复文本中。事后重建将非常困难。

决策的容器：在设置阶段需要创建的是决策的容器，而不是做出决策本身。任务是预先约定好使命、技术栈、路线图、规范、验证笔记和报告将存放的位置。这些目录的内容将在后续课程章节中确定。

用于审计设置的 Qwen 查询：该查询委托智能体读取当前项目结构，检查是否已存在 mission、tech-stack、roadmap、模型规范、验证证据、dbt 模型和评审报告的位置，并生成设置缺口列表（不修改任何文件）。在获得缺口列表之后，可以要求智能体仅创建缺失的目录和空白模板。此阶段不得要求其编写 SQL。

设置完成的标准：良好的设置可以通过一个简单的测试来检验：在清除上下文后，新智能体应能够理解使命的位置、允许使用的技术栈、正在构建的数据集市以及如何证明完成度。如果继续工作需要复述聊天内容，则说明项目尚未完成设置。设置完成的标志不是文件夹被创建出来，而是这些文件夹开始承载决策。

典型的设置错误：立即要求智能体「搭建 lakehouse」——这是一个范围过宽的查询。在设置阶段，应创建决策的容器，而不是做出决策本身。此类查询会让智能体在聊天中讨论技术栈、格式和编排器，而在仓库中却不会出现任何结构性单元。

练习题：标题：创建最小化的项目骨架

题目：在空仓库中创建以下目录结构：specs/（包含 models/、validation/、reviewer-reports/ 子目录）、models/（包含 staging/、intermediate/、marts/ 子目录）、tests/。添加空白的占位文件：specs/mission.md、specs/tech-stack.md、specs/roadmap.md、AGENTS.md、dbt_project.yml、profiles.yml。请描述你使用的命令及其执行顺序，并解释为什么目录创建顺序对后续与智能体的协作很重要。

解答：步骤 1. 使用一条命令创建根目录：mkdir -p specs/models specs/validation specs/reviewer-reports models/staging models/intermediate models/marts tests。-p 标志用于通过一条命令创建嵌套目录。步骤 2. 创建空白占位文件：touch specs/mission.md specs/tech-stack.md specs/roadmap.md AGENTS.md dbt_project.yml profiles.yml。步骤 3. 在 Git 中固定结构：git init && git add . && git commit -m 'scaffold: 最小化的项目结构'。步骤 4. 解释顺序：specs/ 是契约，models/ 是实现，tests/ 是验证。先创建 specs/ 再创建 models/ 确立了「意义优先于代码」的原则。如果先创建 models/，智能体会在使命和规范位置尚未确定之前就开始编写 SQL，真相之源就会转移到注释和聊天回复中。

难度：中级

标题：按最小模板编写 AGENTS.md

题目：根据本章内容，用五条规则填写 AGENTS.md。请简明扼要地表述：1) 智能体在修改 dbt 模型前应阅读什么；2) 不得暴露什么；3) 未经确认不得修改什么；4) 应运行哪个命令；5) 应如何汇报。并解释为什么每条规则都应简短，以及为什么 AGENTS.md 不适合用来描述数据集市。

解答：步骤 1. 第一条规则——预读：「在修改 dbt 模型前，请阅读 mission、tech-stack、roadmap 和相关模型规范」。步骤 2. 第二条规则——PII 限制：「不要在 marts 中暴露直接的 PII 字段」。步骤 3. 第三条规则——禁止静默修改契约：「未经确认不得修改 grain、SLA 或契约字段」。步骤 4. 第四条规则——强制验证：「当 dbt 可用时运行 dbt build」。步骤 5. 第五条规则——汇报格式：「请基于验证证据汇报，而非做出承诺」。步骤 6. 解释：规则必须简短，因为冗长的 AGENTS.md 会变成无人阅读的百科全书——无论是人还是智能体都不会读。数据集市的描述应放在 specs/models/ 中，而不是 AGENTS.md 中，因为这是产品知识而非智能体行为。

难度：中级

标题：通过 Qwen 查询审计骨架

题目：起草一个发送给 AI 智能体的查询，要求它：1) 读取当前项目结构；2) 检查是否已存在 mission、tech-stack、roadmap、模型规范、验证证据、dbt 模型和评审报告的位置；3) 生成设置缺口列表（不修改文件）。然后起草第二个查询，该查询基于缺口列表仅创建缺失的目录和空白模板，不编写 SQL 也不填写规范内容。

解答：步骤 1. 第一个查询（仅读取）：「请读取当前项目结构。检查是否存在 mission、tech-stack、roadmap、模型规范、验证证据、dbt 模型和评审报告的位置。生成设置缺口列表。不要修改任何文件」。步骤 2. 第二个查询（仅创建容器）：「基于缺口列表，仅创建缺失的目录和空白模板。不要编写 SQL，也不要填写规范内容」。步骤 3. 解释：第一个查询与修改操作分离，因此智能体不会意外覆盖现有文件，团队也能看到清晰的缺口列表。第二个查询仅限于创建空白容器，因此智能体不会过早进入编写模型或讨论技术栈的阶段。这正是「决策的容器，而非决策本身」的原则。

难度：中级

标题：按工件编制路线图

题目：为一个虚构的银行数据项目「Customer 360」编制包含五个要点的路线图。每个要点应指明工件或验证证据，而非分层。解释为什么「已编写模型 marts/customer_360.sql」是糟糕的表述，而「Customer 360 数据集市已通过评审者验证」是良好的表述。为每个要点添加预期的证据（其存放位置）。

解答：步骤 1. 要点 1：「raw/staging 可复现」——证据存放在 specs/validation/（可复现运行的报告）和 tests/（通过的 dbt build 测试）中。步骤 2. 要点 2：「Customer 360 契约已批准」——证据存放在 specs/models/customer_360.md，并附有数据集市负责人的签字。步骤 3. 要点 3：「Customer 360 数据集市已通过验证」——证据存放在 specs/validation/customer_360.md（关于字段、grain 和 SLA 的验证报告）。步骤 4. 要点 4：「风险、信贷和同意书的数据集市已通过评审者验证」——证据存放在 specs/reviewer-reports/。步骤 5. 要点 5：「实践考核的发布证据已就绪」——这是一个综合要点，引用前述所有目录。步骤 6. 解释：「已编写模型」的表述描述的是动作而非结果；「已通过评审者验证」的表述描述的是证据。按工件编制的路线图能立即显示哪些证据尚未收集以及应存放在哪里。

难度：中级

标题：划分 AGENTS.md 与 specs 的职责范围

题目：现有以下四个陈述：1)「PostgreSQL 是允许使用的存储层，因为银行已在使用」；2)「智能体在未阅读 mission.md 之前不应运行 dbt build」；3)「Customer 360 包含 customer_id、full_name、birth_date、risk_score 字段」；4)「每个关于数据集市的 PR 都必须附有评审者报告」。请将它们分配到仓库中正确的文件，并解释为什么 AGENTS.md 不适合放置陈述 1，而适合放置陈述 2。

解答：步骤 1. 陈述 1（「允许使用 PostgreSQL，因为银行已在使用」）应放入 specs/tech-stack.md——这是关于允许使用的技术栈及其选择理由的描述，而非智能体行为。步骤 2. 陈述 2（「智能体在未阅读 mission.md 之前不应运行 dbt build」）应放入 AGENTS.md——这是智能体在执行操作前的行为规则。步骤 3. 陈述 3（「Customer 360 包含……字段」）应放入 specs/models/customer_360.md——这是具体模型的契约，而非行为规则。步骤 4. 陈述 4（「每个 PR 必须附有评审者报告」）应同时放入 AGENTS.md（作为智能体的行为规则）和 specs/roadmap.md（作为流程要求）。步骤 5. 解释：AGENTS.md 不适合放置陈述 1，因为它描述的是技术栈而非行为；混合使用会导致 AGENTS.md 膨胀，使智能体不再阅读。AGENTS.md 适合放置陈述 2，因为这是一条「操作前先阅读」的行为规则。

难度：高级

案例研究：标题：银行 Customer 360：聊天如何「吞掉」被遗忘的 PII 限制

场景：由三位分析师和 AI 智能体组成的团队正在为银行风险部门构建 Customer 360 数据集市。在项目初期，团队在聊天中约定 email 字段在未经脱敏处理的情况下不得输出到 marts，且数据集市的 grain 为「同一客户在同一截止日期对应一行」。这些约定仅保留在对话框中。两周后，一位新分析师加入仓库，并向智能体发送了全新的上下文。

挑战：在执行 /clear 命令后，智能体在项目中找不到任何关于 email 脱敏和数据集市 grain 的提及。它生成了一个将 email 以明文形式输出的数据集市，且 grain 被模糊化为「同一客户的每个操作对应一行」——因为这更符合风险部门当前请求的便利性。SQL 通过了所有 dbt build 测试并显示为绿色，但违反了仅存在于聊天中的约定。风险部门收到包含 PII 且 grain 不正确的数据集市，导致任何聚合都失去意义。

解决方案：团队暂停了发布，手动恢复了聊天记录，并在仓库中固定了两个新目录：specs/models/customer_360.md（包含 grain、SLA、字段列表以及对明文 email 的明确禁止），以及用于存放验证笔记的 specs/validation/。在 AGENTS.md 中添加了两条规则：「不要在 marts 中暴露直接的 PII 字段」和「未经确认不得修改 grain、SLA 或契约字段」。在 specs/tech-stack.md 中记录了 PII 脱敏是流水线中的强制步骤，而非可选项。路线图被改写为按工件组织：「契约已批准 → 数据集市已验证 → 数据集市已获评审者批准」。

结果：一周后数据集市被重写：email 仅以脱敏形式输出，grain 恢复为「同一客户在同一截止日期对应一行」。新加入的分析师无需复述聊天内容即可继续工作：他阅读了 specs/models/customer_360.md，立即看到了所有限制。绿色的 dbt build 不再是就绪的标志——现在，完成度通过 specs/validation/ 和 specs/reviewer-reports/ 的内容来证明。

经验教训：仅保留在聊天中的约定会在第一次 /clear 时消失，且对新成员不可见

绿色的 dbt build 不等于产品就绪——还需要规范和验证证据

AGENTS.md 应是简短的行为规则列表，而不是规范的副本

按工件编制的路线图能立即显示哪些证据尚未收集

specs/models/、specs/validation/ 和 specs/reviewer-reports/ 目录应在第一个 SQL 模型出现之前就存在

相关概念：项目记忆 vs 聊天记忆

AGENTS.md 与 specs 的划分

意义、验证与评审的分层

按工件编制的路线图

设置完成的标准

标题：电商分析：尝试「立即搭建 lakehouse」

场景：一位电商项目经理要求 AI 智能体「搭建用于销售分析的 lakehouse」。该项目既没有 mission.md，也没有 tech-stack.md，更没有 specs/。仓库中只有一个空的 README 和包含原始导出文件的 data/ 目录。

挑战：智能体一开始试图在 Spark、ClickHouse、BigQuery 和 Snowflake 之间做选择，并在聊天中直接讨论数据模型、文件格式和编排器。一小时后，对话膨胀到数百条消息，但仓库中除了 README 之外仍没有任何结构性单元。当第二位分析师加入时，他无法理解已做出哪些决策，因为这些决策分散在聊天中。任何 /clear 都会清除上下文，工作不得不从头开始。

解决方案：经理停止了对话，并按照本章的规则开始进行项目设置。他创建了 specs/mission.md（「电商销售分析，重点关注复购行为」）、specs/tech-stack.md（「使用 ClickHouse 作为存储，dbt 作为转换层，Airflow 作为编排器」）、按工件组织的 specs/roadmap.md 以及包含五条简短行为规则的 AGENTS.md。在此之后，向智能体发送了用于审计骨架的 Qwen 查询：「请读取当前项目结构。检查是否存在 mission、tech-stack、roadmap、模型规范、验证证据、dbt 模型和评审报告的位置。生成设置缺口列表。不要修改任何文件」。基于缺口列表，智能体被要求仅创建缺失的目录和空白模板，不编写 SQL。

结果：30 分钟后骨架就绪，第二位分析师在设置完成之后进入项目。他花了 10 分钟阅读了 mission.md、tech-stack.md 和 roadmap.md，立即理解了项目的目标和原因。之后团队才进入模型规范阶段，最后才编写 SQL。新成员入职时间从几天缩短到一小时。新智能体在 /clear 之后也能在无需复述聊天内容的情况下理解项目，这验证了设置完成的标准。

经验教训：对智能体的过宽查询（「搭建 lakehouse」）会导致对话中无工件产出

项目设置是创建决策的容器，而不是做出决策本身

带有修改禁令的 Qwen 查询非常适合用于骨架审计

按工件编制的路线图有助于避免「为分层而分层」

简短的 AGENTS.md 比冗长的指令更有效