project-context-pack

name	project-context-pack
description	把一个模糊的项目目标,通过和用户**一个问题一个问题、无限循环地持续讨论**(对抗式追问、反思、主动澄清),逐渐逼到清晰,并渐进沉淀成一套分层、自包含、任何人读完即可开工的设计上下文包。当用户描述了一个还不完全清晰的目标——"我想做一个 X""我们重写 / 重新设计 / 改造一下 Y""帮我想清楚这个东西到底要做什么"——务必使用本 skill。它适用于全新项目和老项目改造 alike。即使用户没明说,只要目标还模糊、需要持续讨论才能清晰,就主动触发它,不要等用户说"我要做设计文档"。

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 任务包合同模板 + 派工规则。