主题：第五部分 项目初始配置
难度级别：中级
预计学习时间：2-3小时（理论+实践）
前置知识： 命令行基础（bash/zsh）
Git 基础（init, add, commit, status）
Node.js 和 npm 基础（安装包、package.json）
TypeScript 基础知识（tsconfig、编译）
.gitignore 概念理解
学习目标： 独立创建最小 SDD 脚手架：Git 仓库、严格模式 TypeScript 项目、基础文件夹结构和起始文档
通过 QWEN.md 为代理配置知识预加载系统，并理解代理开始工作前应该读取哪些文件
区分初始配置与过早实现产品功能，能够解释为什么框架和数据库要推迟到立宪阶段
通过 Qwen Code 检查仓库就绪状态，正确解读其建议而不允许过早修改
概述：SDD（规范驱动开发）方法论中的项目初始配置，是创建最小、清晰且安全的基础，以便后续代理工作。与传统开发中此阶段经常"立即构建应用"不同，SDD 的初始配置任务更为谦逊：准备工作空间、建立 Git 边界、创建知识预加载机制、记录参与者的初始意愿。此阶段不包括选择 Web 框架、配置数据库、实现 API 或产品路由——所有这些决策有意识地推迟到项目立宪文档（mission.md、tech-stack.md、roadmap.md）创建之后。学习项目 AgentClinic——一个虚构的 AI 代理心理健康诊所——作为掌握这些原则的实践模型。完成此阶段后，你将拥有：Git 仓库、包含产品愿景的 README.md、包含代理行为规则的 QWEN.md、.qwen/settings.json 配置、包含空 src/index.ts 的最小 TypeScript 模板、带有 typecheck 脚本的 package.json、strict: true 的 tsconfig.json，以及第一条具有意义提交信息的提交。
核心概念： SDD 脚手架：足以开始规范工作的最小项目结构。仅包含基础设施元素，不含产品逻辑。类似于建房前的脚手架——不是房子，但是安全的工作平台。
知识预加载：在每个代理会话开始时预先加载关键上下文知识的实践。在企业文档中，这指在 QWEN.md 中固定必须阅读的文件，使代理不必浪费 token 猜测项目结构。这与临时提示有本质区别：规则是形式化且可重复的。
项目立宪：三个文档——specs/mission.md（项目为何存在）、specs/tech-stack.md（使用什么技术栈及原因）、specs/roadmap.md（当前阶段及后续计划）。在初始配置之后创建，但代理必须通过 QWEN.md 预先知道它们的存在。
TypeScript 严格模式：tsconfig.json 中 strict: true 的配置，SDD 项目强制要求。防止隐式 any、可选的 null 检查等运行时错误来源。在初始配置阶段，这是对所有后续规范可靠性的投资。
Git 提交边界：阶段完成后进行有意义提交的实践。第一条提交"Initialize AgentClinic scaffold"创建清晰的历史节点：此前是基础设施，此后开始立宪工作。有助于回滚和追踪决策何时做出。
过早实现：反模式，代理或开发者在初始配置阶段开始编写业务逻辑、选择框架或设计数据库。在 SDD 中，这违反了延迟决策原则：基础设施与产品决策在时间上分离。
三件事规则：代理在首次行动前必须知道三件基本事项：项目为何存在（mission）、使用什么技术栈（tech-stack）、当前处于什么阶段（roadmap）。这是有意义工作的最小上下文。
练习题目： 标题：从零创建脚手架
问题：你被指派在新文件夹中启动 AgentClinic 学习项目。执行所有初始配置命令：创建文件夹结构、初始化 Git 和 npm、安装 TypeScript、创建所有必要文件。然后检查 npm run typecheck 是否无错误通过，以及 git status 仅显示应在 .gitignore 中的未跟踪文件。
解答：1. mkdir agentclinic && cd agentclinic
- git init
- npm init -y
- npm install -D typescript @types/node
- npx tsc --init
- mkdir -p src specs .qwen
- touch src/index.ts
- 编辑 tsconfig.json：设置 "strict": true
- 在 package.json 中添加脚本 "typecheck": "tsc --noEmit"
- 创建 .gitignore，内容来自课程材料（node_modules/, dist/, build/, .env, .env., .qwen/memory/, .idea/, .vscode/）
- 创建包含项目愿景的 README.md
- 创建包含知识预加载模块的 QWEN.md
- 创建 .qwen/settings.json（空或安全配置）
- 检查：npm run typecheck（空 src/index.ts 应通过）
- 检查：git status（node_modules 不应显示为未跟踪）
- git add README.md QWEN.md package.json package-lock.json tsconfig.json src .qwen
- git commit -m "Initialize AgentClinic scaffold"
难度：初级
标题：分析过早实现请求
问题：同事给你发送了一个代理提示："构建 AgentClinic 应用。为 API 配置 Hono，通过 Drizzle 连接 SQLite，创建代理和治疗表，实现 CRUD 路由。使用严格模式的 TypeScript。"解释此请求违反了哪些 SDD 初始配置原则，并按方法论重写该请求。
解答：原始请求中的违规：
- "构建应用"——混淆基础设施与产品逻辑
- "配置 Hono"——在尚无立宪文档时选择 Web 框架
- "通过 Drizzle 连接 SQLite"——在 tech-stack.md 之前选择 ORM 和数据库
- "创建表"——无规范的数据库模式
- "实现 CRUD 路由"——在 mission.md 之前的产品路由
重写后的请求： "为 AgentClinic 项目准备 SDD 仓库。 暂时不要选择 Web 框架——此决策推迟到 specs/tech-stack.md。 不要实现产品路由——先创建 specs/mission.md。
确保：
- Git 仓库已初始化
- TypeScript 配置 strict: true
- package.json 中有 typecheck 脚本
- 已创建 src/、specs/、.qwen/ 文件夹
- QWEN.md 包含知识预加载规则
- README.md 反映产品愿景
- .gitignore 排除构建产物和密钥
所有关于 Hono、SQLite、Drizzle 和业务逻辑的内容——记录为后续阶段的开放问题。"
难度：中级
标题：通过 Qwen Code 诊断仓库
问题：你已完成初始配置，但通过 Qwen Code 检查时，代理建议："我们直接添加 Hono 用于未来 API 吧，这会加速开发。而且我看到你没有测试——我来安装 Vitest。"你的任务：向代理表述回应，阻止过早行动，同时保持建设性语气，并解释为什么这些建议超出当前阶段范围。
解答：给代理的回应： "感谢你的主动，但我们遵循 SDD 的阶段纪律。
Hono：Web 框架选择是产品决策，应进入 specs/tech-stack.md 并附论证。目前我们还没有 specs/mission.md，因此不知道是否需要 HTTP 服务器（项目可能是 CLI 工具或库）。推迟到立宪阶段。
Vitest：测试很重要，但测试策略（单元、集成、端到端）取决于我们尚未设计的架构。现在添加 Vitest 会产生测试未规范内容的虚假就绪感。在 roadmap.md 中记录为创建首个功能规范后的任务。
当前任务：仅检查基础设施。确认：
- TypeScript 严格模式正常工作
- Git 仓库干净
- QWEN.md 包含知识预加载规则
- 所有初始配置文件就位
如果一切正常——结束会话，不做更改。"
难度：中级
标题：.qwen/settings.json 安全审计
问题：你的 .qwen/settings.json 中出现以下行： { "model": "qwen-coder-plus-latest", "apiKey": "sk-qwen-2b3c...9f4a", "temperature": 0.7 } 分析问题，确定正确操作，执行并解释为什么模型配置可以保留在仓库中，而 apiKey 不可以。
解答：问题：apiKey 是绝不能提交到 Git 的密钥。即使在私有仓库中，这也违反最小权限原则，并在克隆、分叉或意外发布时造成泄露风险。
操作步骤：
- 立即通过 API 提供商管理面板撤销密钥
- 从 .qwen/settings.json 中删除密钥
- 将 apiKey 作为模式添加到 .gitignore（可选："apiKey" 或更具体的模式）
- 将密钥移至环境变量：在 .env 中设置 export QWEN_API_KEY=sk-...
- .env 已添加至 .gitignore（应已存在）
- 更新文档：说明密钥通过 QWEN_API_KEY 传递
- 仅提交修复后的 .qwen/settings.json
为什么 model 可以保留：模型名称是团队配置，不敏感，不授予资源访问权限，并帮助所有开发者使用统一版本。类似于 package.json 中的 "node": "20"——是声明性要求，而非密钥。
为什么 apiKey 不可以：这是授予付费资源访问权限的凭证。提交它等同于发布密码。
难度：高级
案例研究： 标题：「快速启动」团队与立宪技术债务
场景：初创公司 HealthAI 决定开发远程医疗平台。三名开发者获得 Claude Code 访问权限，决定「不浪费时间在官僚流程上」。第一周他们创建仓库，立即安装 Next.js、Prisma、PostgreSQL，通过 Auth0 配置认证，甚至做了预约原型。所有内容直接提交到 main，无中间阶段。
挑战：两周后投资者要求转型：产品应成为面向企业诊所的 B2B 平台，而非面向私人患者的 B2C 服务。结果：Next.js 服务端组件不适合要求的微服务架构；Prisma ORM 创建了针对 B2C 优化的模式强耦合；Auth0 的企业 SSO 需要不同的许可计划；预约作为功能完全取消——需要的是与现有 HIS 系统集成的 API。团队花费 6 周重构，而非 3 天立新宪。
解决方案：同公司并行项目（分析模块）正确应用了 SDD 初始配置。他们：2 小时创建脚手架；3 天与产品经理共同完成 specs/mission.md、tech-stack.md、roadmap.md；获得投资者对立宪的批准；然后才开始实现。当类似转型需求到来时——变更仅涉及 specs/，基础设施一天内适配。
结果：「快速启动」项目比采用 SDD 的竞争对手晚 4 个月上市，错失关键窗口期而关闭。分析模块成为存活平台的核心。内部复盘发现：「快速启动」73% 的技术债务在编写首个规范前产生。
经验教训： 过早选择框架创造「冻结决策」，解冻成本高昂
缺乏立宪使转型时无法论证拒绝功能——一切看似「已投入」
2 小时「无聊」的初始配置节省 6 周重构时间
投资者和利益相关者将立宪视为讨论文档，而将代码视为既成事实
相关概念： 过早实现
SDD 脚手架
项目立宪
Git 提交边界
标题：银行中的知识预加载企业实施
场景：大型银行部署代理维护 COBOL 遗留系统。200 名开发者在不同团队使用不同代理工作。问题：每次会话开始都有 10-15 分钟「预热」，代理猜测 40 个微服务组成的单体仓库结构，经常出错并提出不相关的重构建议。
挑战：时间损失灾难性放大：200 开发者 × 每天 2 次会话 × 12 分钟 = 每天 80 人小时用于「了解情况」。同时代理周期性「幻觉」架构，建议迁移不存在的服务，或忽略监管关键限制。
解决方案：平台工程团队为所有微服务创建统一初始配置脚手架：标准 QWEN.md 含知识预加载模块，强制读取 service-manifest.yaml（specs/mission.md 的类比）、compliance-rules.md（监管限制）和 current-sprint.md（活跃规范）。.qwen/settings.json 标准化并存储于中央模板仓库。开始任何服务工作时，开发者克隆模板，代理立即获得正确上下文。
结果：「预热」时间从 12 分钟缩短至 2 分钟。架构幻觉按代码质量指标下降 87%（更少的评审回退）。模板成为所有新服务强制要求，遗留系统改造耗时 3 个月而非计划的 9 个月。
经验教训： 知识预加载仅在初始配置标准化时才可扩展
监管限制必须在必读中——代理不直观理解合规
集中式 .qwen/settings.json 模板防止团队间配置漂移
预热时间节省在 2-3 周内补偿模板基础设施投入
相关概念： 知识预加载
三件事规则
SDD 脚手架
学习建议： 将材料学习两遍：第一遍——严格按命令操作，创建相同脚手架；第二遍——一周后，用不同名称创建新项目，检验记忆和顺序理解
维护「延迟决策日记」：每次想「直接添加功能」时，记录想添加什么及为何过早。一个月后核对——这些决策是否正确延迟？
使用「红队」方法：请同事或假想对手用「我们直接...」提示攻击你的脚手架，练习以有说服力的拒绝和阶段性解释回应
视觉学习风格：绘制项目状态转换图（脚手架 → 立宪 → 功能规范 → 实现），标注每个阶段出现的文件
听觉学习风格：执行前大声口述命令——激活其他记忆通道并帮助发现错误
动觉学习风格：物理删除文件并从头重建脚手架至少 3 次，直到命令成为肌肉记忆
创建「反诱惑」清单——列出此阶段不应做的事，挂在工作区旁
向他人练习解释「无聊初始配置」概念：能简单有说服力地解释为何重要——是理解的最佳指标
额外资源： TypeScript 官方文档——tsconfig.json：https://www.typescriptlang.org/tsconfig ——编译器选项参考，特别是 strict 部分
Git 书——分支基础：https://git-scm.com/book/zh/v2 ——关于提交和历史的章节，理解 Git 边界
「架构决策记录」（ADR）模式：https://adr.github.io/ ——固定延迟决策的方法论，与 SDD 立宪相关
「LLM 代理知识预加载」文章：该实践的概念基础，建议学术数据库搜索该术语以深入理解
Qwen Code 文档：https://github.com/QwenLM/qwen-code ——QWEN.md 和 .qwen/settings.json 的最新建议
Git 交互式训练器：https://learngitbranching.js.org/?locale=zh_CN ——巩固将提交作为阶段边界的理解
「规范驱动开发」课程：本材料的完整课程来源——后续部分的上下文
总结：SDD 中的初始配置是创建最小但可靠的基础以进行后续规范工作的纪律。其关键原则：基础设施与产品决策在时间上分离；通过知识预加载形式化代理上下文；严格模式 TypeScript 作为质量投资；有意义的 Git 边界作为阶段固定点。反模式是过早实现，将「无聊」配置变成「构建应用」。正确执行的阶段产出：Git 仓库、README.md、含初级阅读规则的 QWEN.md、.qwen/settings.json、strict: true 的 TypeScript 脚手架、含 typecheck 的 package.json，以及首次提交。其余一切——框架、数据库、业务逻辑——有意识地推迟到项目立宪（mission、tech-stack、roadmap）创建及后续功能规范。此阶段「无聊」带来的节省，以需求变更时节省的重构周数衡量。