project-context-pack

# Project Context Pack — 把模糊逼到清晰 ## 这个 skill 在解决什么 你刚听到一个项目目标。它大概率是模糊的:"我想做一个 X""我们重写一下这块""把 Y 改造一下"。 **关键前提:这时候连用户自己往往也还没想清楚要什么。** 这不是用户的失职,这是复杂项目的常态。直接动手实现,几乎一定会:① **跑偏**(被某个酷方案牵走);② **重复争论**(同一决定讨论三遍,没人记得上次为什么那么定);③ **文档打架**(PRD 说 A,设计说 B,新人不知道信谁)。 本 skill 的任务:和用户一起,把一团模糊逼成一套**自包含的设计上下文包** —— 任何 agent 或人读完它,就能创建第一个实现任务,无需回溯历史、无需重复讨论、无需猜哪个文档权威。 核心信念:**"概念先于工程"**,而概念是靠**持续讨论**磨出来的,不是一次性想清楚的。 ## 双轨:循环为体,阶段为用 这个 skill 有两条轨,同时运行: - **上轨 · 循环引擎(为体)**:你**怎么**和用户讨论 —— 每一轮怎么追问、怎么沉淀、怎么控制下一步。这是主交互模式,贯穿始终。 - **下轨 · 阶段(为用)**:讨论**澄清出来的东西往哪放** —— 七层骨架作为沉淀的目的地,六个 Phase 作为循环会自然经过的里程碑。 循环驱动阶段,阶段收纳循环的产物。两条轨互相引用:每一轮循环产出的结论,落到下轨的某一层;每一层的空缺,提示上轨下一轮该问什么。 --- ## 上轨 · 循环引擎 ### 三个引擎(每一轮用什么去逼清晰) 澄清不是"温和地问用户想要什么"——用户不知道。靠三个引擎主动把模糊点逼出来: **引擎一 · 对抗(找漏洞、逼选择)。** 四类标准动作,每轮至少用一类: 1. **术语对齐**:用户用词和已有词汇/概念冲突时,立刻点名。"你说的'账户'是 Customer 还是 User?这是两个东西。" 2. **模糊磨利**:把过载词逼成精确术语。"你说的'快',是 P99 < 100ms,还是人感觉不到卡?这两个差一个数量级。" 3. **场景压测**:编造边界 case 压测设计。"如果两个用户同时改同一条记录,你的方案谁赢?" 4. **代码/文档对质**:用户说的和代码/文档做的不一致,摆出来对质。"你说这里是只读的,但代码里这个函数在写文件——哪个对?" 此外永远要逼**非目标**(不做什么比做什么更难定)、给每个 chosen 配 rejected。 **引擎二 · 反思(回拉、查自洽、查风化)。** - 回拉北极星:每个新决策问"它和最初那句北极星一致吗?" - 查自洽:新决策和已有决策/已有概念冲突吗? - 查风化:一个承重决策,支撑它的理由还成立吗?只进不出的决策库会腐烂。 **引擎三 · 主动(逼出用户没想到的致命点)。** 停止条件(什么情况必须停下来问人)、自主边界(哪些 agent 可拍板、哪些必须人确认)、冲突裁决(文档打架谁说了算)、把模糊显式化为开放项。 ### 核心循环:每一轮怎么走 讨论以**轮**为单位推进。一轮只做下面这一件事,做完才进下一轮: ``` 1. 选一个引擎 —— 当前最缺什么 clarity?对抗/反思/主动,选一个。 2. 抛【一个】问题 —— 一次只问一题。附上【你推荐的答案 + 为什么】。 (带推荐答案是为了对抗"用户也不知道"的僵局: 给一个具体锚点,用户只需同意/修正,比空问高效得多。) 3. 等用户回应 —— 用户同意/修正/否决你的推荐。 4. 判断这轮定了没 —— settled(有结论)→ 进第 5 步沉淀; 还在探索/没共识 → 不写,留在"讨论缓冲区",下一轮接着磨。 (不是每轮都该写。把没定的东西写进文档 = 占位壳污染。) 5. 沉淀 + 报告 —— settled 时:写进下轨对应层的具体文件(骨架已搭好,见下), 并【明确告诉用户】写入了哪个文件、什么内容,顺手更新 README 状态表。 沉淀【可见】,不静默——用户要看得见讨论正在变成文档。 6. 指令面板 —— 把下一步的控制权交给用户(见下)。 ``` **为什么"一次一题":** 一次抛五个问题,用户会随便答或跳过,模糊点继续模糊。一次一题,每题都带推荐答案 + 沉淀,才是"逐渐逼清晰"。"无限循环"就由这样一个一个的回合组成,直到所有承重点都清晰、剩下的都进了开放项。 ### 两条硬规则(防止循环变味) 1. **能查代码/文档就别问用户。** 凡是能从代码、已有文档、git 历史里读出来的答案,去读,不要拿来问用户。问用户是为了逼**判断**和**取舍**,不是为了省自己查资料的力气。违反这条,循环会退化成烦人的审讯。 2. **口头 defer 不算数。** 用户说"这个以后再说""暂时不定",**必须**当场落进开放项(open question + owner + 何时锁定)或被否决方案表。口头 defer 等于不存在,它一定会变成三个月后没人记得的坑。 ### 循环控制面板 + ASCII 结构图 每轮沉淀后,把控制权交给用户,并可视当前状态: **指令面板**(用户每轮可选): - **`推进`** —— 接受当前结论(settled),沉淀并报告写入哪,进下一题。 - **`深挖此节`** —— 当前这点还没透,**不沉淀**,围绕它再问一轮(留在讨论缓冲区)。 - **`沉淀`/`落盘`** —— 用户主动喊:把目前讨论缓冲区里已经清楚的内容,集中成文写进对应层并报告。 用于深挖了好几轮后一次性落盘,或用户想随时手动固化。给用户一个"现在就存下来"的手柄。 - **`拉回北极星`** —— 觉得跑偏了,回到北极星重新校准。 - **`引入新视角`** —— 换个角色/立场看(比如"站在运维角度""站在未来维护者角度")。 **沉淀的双保险:自动 + 手动。** 每轮 settled 自动沉淀(防止"聊久了忘记写、推理丢失"——这是 grill 明确警告的失败模式);同时给用户 `沉淀` 手动指令(让用户能在深挖多轮后主动固化、随时掌控时机)。两者都【可见报告】,绝不静默写盘。 **每隔几轮,画一张 ASCII 结构图**(不是复述内容,是暴露结构): - 标出当前已定/未定的承重点、它们之间的关系、张力所在(哪里还没自洽、哪个决策依赖尚未锁定的开放项)。 - 形式随结构而定:分层图 / 因果环 / 2×2 矩阵 / 依赖树 —— 哪种最见骨用哪种。 - 目的:让用户(和你自己)一眼看到"还差哪些点就清晰了",循环不是漫无目的的。 --- ## 下轨 · 阶段(澄清出东西往哪放) 七层骨架(沉淀的目的地),各层单向依赖,上层定义、下层只能落实: ``` project-context/ ├── README.md ← 读法总图 + 权威优先级表 + 当前状态 ├── 00-goal-boundary.md ← 北极星 / 设计箴言 / Done / 非目标 / 停止条件 / 自主边界 ├── 10-foundation/ ← 是什么 / 为什么(定义层,不被实现反向改写) ├── 20-contracts/ ← 必须怎么做(可被 reviewer / CI 执行的约束) ├── 30-roadmap/ ← 什么时候做 + 验收状态 ├── 40-task-packets/ ← 可派工的任务包(设计 → 实现的桥梁) ├── 60-diagrams/ ← 图(非规范,辅助,永不覆盖正文) └── 90-evidence/ ← 证据 / 调研 / 原始讨论(非规范,需"晋升"才成决策源) ``` 循环会在下面这些里程碑自然停留(顺序非强制,可回溯): - **Phase −1 · 现状审计(动手追问前先做)。** 别把用户的半成品当白纸。先读已有代码、已有文档、git log。三问:0A 这是真问题还是伪需求?0B 现有代码/方案已经解了多少(别重建已存在的东西)?0C 描述一下 12 个月的理想态,本计划是靠近还是远离它? - **Phase −0.5 · 先搭骨架(进入循环前必做)。** 循环每轮要"沉淀到对应层",可这些层得**先在磁盘上物理存在**,否则 agent 只能临时编路径、内容散落、互相矛盾(这正是同一概念定义不一致的根源)。所以追问前先定落点: - **空项目**:和用户商量在哪建(项目名、放哪),建一个新文件夹存这个包。 - **已有项目**:把包搭在项目内(如 `docs/project-context/` 或 `harness/context/`,和用户确认)。 - 然后**跑 `scripts/scaffold.sh <目标目录>`**:它把 skill 自带的**完整骨架**(`skeleton/` 真实文件)复制过去 —— 顶层 README 地图(读法总图/权威优先级表/**当前状态表**)、goal-boundary 章节骨架、**每层一份 README 导引**(讲清这层管什么 / 典型文件 / 铁律)、decision-log 骨架、`30-roadmap/milestones/_TEMPLATE/`(里程碑定义模板)。脚本幂等、绝不覆盖已有文件。 - **关键区分:层导引 README / 章节骨架 / 里程碑模板 = 地图和落点(该有,每次导航都被消费);空的内容文件假装有实质 = 占位壳(该禁)。** 别把两者混了 —— 骨架自带的 README 是地图,不是壳;而 `10/20/30/40` 里的**内容文件仍按需懒生**(讨论清楚才落)。 - 新建里程碑时复制 `30-roadmap/milestones/_TEMPLATE/` 为 `m1-<名字>/` 再填(North Star / In Scope / Non-goal / 入口条件 / 验收标准 / 依赖)。 - **Phase 0 · 锚定北极星 + 设计箴言。** 一句话核心问题;一两句口诀式取舍(争论时的引力)。 - **Phase 1 · 目标边界。** Done(外部可观察)/ Non-goals / Constraints / Stop-Escalate / Autonomy。 - **Phase 2 · foundation。** 产品问题、领域模型、系统架构、词汇表、边界。 - **Phase 3 · contracts。** 把定义落成**可执行**约束(逐条问:这能被 reviewer/CI 执行吗,还是只是愿望?)。 - **Phase 4 · 决策治理。** Decision Log(每条标【硬/定/开】+ 理由 + 出处 + rejected)、被否决方案表、权威优先级表、开放项。 - **Phase 5 · 路线 + 任务包。** 里程碑/依赖/验收状态;任务包锁死 inputs/reading_list/outputs/forbidden/gates/stop_condition。 **ADR 准入三门槛**(Phase 4,只有三个全中才写 ADR,否则不写):① 难逆转(改主意成本大);② 无上下文会让人困惑(未来读者会问"为什么这么做");③ 真实取舍的结果(有过被否决的替代方案)。三门槛是防止 decision log 膨胀的克制。 **整个包的完成判据**(何时可创建第一个实现任务):读完整包即可派工,无需回溯历史。详细 checklist 见 `references/skeleton.md` 末尾。 --- ## 贯穿原则(为什么这么做) - **概念先于工程,不预建 —— 但分清"地图"和"壳"。** 该禁的是**空的内容文件假装有实质**(M3 假里程碑、复述正文的装饰图、为凑齐表格而填的薄理由)—— 这些比没有更糟。该有的是**导航地图和落点**:骨架自带的每层 README 导引、goal-boundary 章节标题、里程碑模板 —— 它们每次导航都被消费,是循环沉淀的去处,不是壳。判据:**这东西每次被读到时帮人找到路 / 知道往哪填吗?是 → 地图,该有;还是只是空着占个位假装完成?是 → 壳,该禁。** 内容文件(`10/20/30/40` 里的具体设计)按需懒生,讨论清楚才落。 - **证据不等于决策。** 调研、原型、对话记录解释"为什么这样",但不能直接覆盖已 canonical 的正文。要用证据推动新决策,再改正文。 - **冲突不靠口头绕过。** 两份文档打架,不要口头解释过去 —— 要么补低优先级文档让它让位,要么新建决策记录正式裁决。 - **沉淀跟着提出者。** 谁提出新决策,谁负责回写所有受影响的 canonical 正文。不能只在对话里说"待会儿补"。 - **回写而非隐式重写。** 早期文档被后续决策覆盖,保留原文 + 加指针,不要悄悄改掉。 - **通用化。** 不引入用户需求里没有的专有平台/框架概念。 ## 怎么用这个 skill(操作建议) 1. **先做 Phase −1 现状审计**,看清用户脑子里已有什么、系统里已有什么。 2. **再搭骨架(Phase −0.5)**:和用户定好包放哪(空项目建新文件夹 / 已有项目放项目内),跑 `scripts/scaffold.sh <目标目录>` 把七层骨架 + README 地图 + goal-boundary 章节先建出来。没有落点,循环就无处沉淀。 3. **进入循环,一轮一题。** 每轮选一个引擎,抛一题(带推荐答案),等回应,settled 才沉淀(可见报告 + 更新 README 状态表),给指令面板。 4. **每轮带上至少一个引擎动作**,否则这轮是浪费。对抗四类动作 / 反思 / 主动,至少用一个。 5. **遵守两条硬规则**:代码优先、无口头 defer。 6. **每几轮画一次 ASCII 结构图**,暴露当前结构和张力,让循环有方向感。 7. **产出文件时**,主代理定结构和术语,大段模板可委托子代理写入,但术语/phase 编号/七层骨架必须与本 SKILL.md 一致。 ## references / skeleton / scripts(按需取用) - `skeleton/` — **完整骨架真实文件**(顶层 README 地图 + goal-boundary 章节 + 每层 README 导引 + decision-log 骨架 + 里程碑模板)。由 scaffold.sh 复制到项目;也可直接读它了解每层该装什么。 - `scripts/scaffold.sh` — 把 `skeleton/` 复制到目标目录(幂等、绝不覆盖已有文件)。进入循环前跑一次。 - `references/skeleton.md` — 七层骨架说明;每个文件"管什么 / 不管什么";整个包的"完成判据"checklist。 - `references/goal-boundary-template.md` — Phase 0–1 详模板:北极星、设计箴言、Done / Non-goals / Constraints / Stop / Autonomy 的填法。 - `references/decision-and-adr.md` — Phase 4 格式:Decision Log 表格、ADR 写法 + 三门槛、被否决方案表、权威优先级表、开放项。 - `references/task-packet-template.md` — Phase 5 任务包合同模板 + 派工规则。