阅读材料: 第5部分. 项目初始设置

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

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

来源

第 5 部分. 项目初始设置

初始设置是为了让智能体和人不是从聊天记录中工作，而是从仓库文件工作。在数据项目中这一点尤为重要：一个被遗忘的关于 grain 或 PII 的约定就可能让看起来通过的 SQL 变得不正确。

最小结构

specs/
  mission.md
  tech-stack.md
  roadmap.md
  models/
  validation/
models/
  staging/
  intermediate/
  marts/
tests/
AGENTS.md
dbt_project.yml
profiles.yml

不需要立刻创建一个可投入生产环境的平台。需要创建的是决策将要落地的地方。如果没有 specs/validation/ 目录，验证性事实几乎肯定会留在聊天记录或 PR 描述中。

在 AGENTS.md 中记录什么

最简规则：

在修改 dbt 模型之前：
1. 阅读 mission、tech-stack、roadmap 以及相应的模型规范。
2. 不要在 marts 中暴露直接的 PII 字段。
3. 未经确认不要更改 grain、SLA 或契约字段。
4. 在 dbt 可用时运行 `dbt build`。
5. 以验证性事实而非承诺进行汇报。

这些规则不能替代规范。它们规定的是智能体的行为。产品承诺、契约字段和验收事实应当保存在 specs/ 中。

路线图

在数据项目中，路线图最好按产物来管理，而不是按"为分层而分层"来管理。例如：

raw/staging 可复现；
Customer 360 契约已确认；
Customer 360 数据集市已验证；
风险、信贷和授权的数据集市已由评审者验证；
实践考核的发布证据已就绪。

由此可以看出，"模型已写好"并不等于"产品已就绪"。

Qwen 提示

读取当前项目结构。
检查是否包含 mission、tech-stack、roadmap、模型规范、
验证性事实、dbt 模型和评审者报告的位置。
列出设置中存在的缺口。不要修改文件。

在列出缺口之后，可以让智能体仅创建缺失的目录和空白模板。在本章中不要让智能体编写 SQL。

读者解读

初始设置看起来很无聊，因为它在屏幕上能展示的结果很少。但项目的记忆正是在这里形成。如果智能体不知道去哪里查找 mission、技术栈、路线图和规范，它就会使用聊天记录的记忆。这种记忆在第一次 /clear 之前很方便，但对下一个人和下一个评审者来说毫无用处。

在数据项目中，目录结构比小型应用程序中的更加重要。SQL 可以在一分钟内写完，但如果事先没有为验证记录留出位置，事实的来源就会出现在智能体觉得方便的地方：注释、命令输出、回答文本。之后很难再恢复。specs/models/、specs/validation/ 和 specs/reviewer-reports/ 这些目录告诉智能体：语义、验证和评审是单独的层次，而不是 SQL 的附注。

本章中的 AGENTS.md 不应变成百科全书。它的任务是在修改前规定智能体的行为：阅读什么、未经确认不能改动什么、运行哪些检查、如何汇报。这些规则越简短，智能体和人真正使用它们的概率就越高。其余细节保存在规范中。

良好的设置有一个简单的测试：在清除上下文之后，新智能体应当能理解 mission 在哪里、允许使用什么技术栈、构建哪些数据集市以及如何证明就绪状态。如果继续工作需要复述聊天内容，那么项目尚未设置完成。设置结束的标志不是目录被创建，而是这些目录开始承载决策。