把项目指引与单次任务请求分开
本文目录
CueSpec 工作流编辑团队撰写 · AI 辅助团队编辑。
把反复适用的项目指引放到后续工作能够找到的位置，把临时实验留在需要它的任务中。将一条笔记提升为指引文件中的规则之前，先明确它的适用范围、有效期和证据状态。
交接时如果只说“使用紧凑布局”，却没有保留实验边界，实验就可能意外变成长期约定。如果把“出现了八行”改写成“始终丢弃空白行”，一条样本观察就可能变成凭空产生的要求。先对笔记分类，可以避免这些含义变化。
下面的虚构仓库有两个代码区域：ui/ 和 parser/。其中的笔记、指引示例及清理历史都是原创教学材料。没有修改任何真实仓库指引或 agent 设置，也没有运行任何项目命令。
为每条笔记明确适用范围和有效期
示例的代码结构很小：
ui/
└─ cards/note-card.tsx
parser/
└─ readers/rows.py
拟议辅助文档：
.github/copilot-instructions.md
.github/instructions/ui.instructions.md
.github/instructions/parser.instructions.md
decisions/0001-parser-boundary.md
evidence/observation-E1.md
evidence/commands-to-check.md
tasks/EXP-12.md
tasks/COPY-13.md
这些路径描述的是虚构设计，不是可以运行的检出目录。这份教学材料包没有提供包清单，也没有实现任何验证命令。
下面是分类前全部八条候选笔记：
| ID | 候选笔记全文 |
|---|---|
| N01 | 在限定范围的修改中，保留已约定的公开输入/输出契约。完成说明中要区分已检查的代码、实际运行的检查，以及仍未运行的检查。 |
| N02 | 在 ui/ 中，仅打开本地预览的控件使用标签 Open preview。让独立的发送操作与它保持清晰区别。 |
| N03 | 在 parser/ 中，read_rows 向调用方返回记录；文件写入和网络操作应放在该函数之外。 |
| N04 | 针对实验 EXP-12，在本地方案中比较笔记卡片的紧凑布局与宽布局。不要把紧凑布局当作项目默认值。 |
| N05 | 这个虚构项目选择独立的解析模块，以便将解析规则与渲染分开讨论。记录为何选择这一边界，以及何时需要重新评估。 |
| N06 | 示例笔记 E1 说，一个样本列表显示了八行，而非九行。原因及空白行的处理方式均未知。 |
| N07 | 一份交接草稿提议使用 npm run check:board 作为验证命令，但没有提供包清单或运行记录。 |
| N08 | 针对任务 COPY-13，研究将笔记卡片文案从 Open preview 改为 Preview now 的提议。只交付文案方案，不要把它变成长期标签约定。 |
这些笔记包含不同类型的信息。重复出现本身不会让 N07 成为已经验证的命令；有效期短，也不会让 N04 对它所属的实验失去重要性。
为每条笔记选择一个主要归属位置
| 笔记 | 主要归属位置 | 适用范围和有效期 |
|---|---|---|
| N01 | 仓库级指引 | 两个代码区域；跨常规任务适用，直到政策改变 |
| N02 | 路径级指引 | ui/；直到它的界面契约改变 |
| N03 | 路径级指引 | parser/；直到它的函数契约改变 |
| N04 | 任务消息 | 仅限 EXP-12；随该实验结束而失效 |
| N05 | 架构决策记录 | 保留历史理由；被后续决策取代时，也保留指向替代记录的引用 |
| N06 | 证据记录 | 一次原因尚未解决的示例观察 |
| N07 | 证据记录及后续核验项 | 尚未检查的命令提议，不是已知可用的操作指引 |
| N08 | 当前任务消息 | 仅限 COPY-13；拟议文案仍有待决定 |
N05 解释为何存在这条边界。N03 则要求常规解析器工作保留当前契约。区分两者的作用，可以避免把每一段架构说明都变成操作命令。
N06 的措辞也需要谨慎。它的证据记录应保留有限的陈述和未知的原因，不应引入任何未经需求选定的空白行过滤规则。
使用限定于具体平台的文件示例
GitHub 文档说明了 .github/copilot-instructions.md 中的仓库级指引，以及 .github/instructions/ 下使用 applyTo glob 模式的路径文件。其 GitHub 上的 Copilot 指引页面 介绍了云端 agent 和代码审查对路径级指引的支持，并说明匹配的仓库级与路径级指引会一起使用。以下语法仅用于演示文档所述的平台范围；将它用于其他场景之前，要检查所选功能和设置。
拟议的仓库级文件全文包含 N01：
# 项目共享指引
保留已约定的公开输入/输出契约，除非当前已约定的任务要改变它们。
完成说明中要区分已检查的代码、实际运行的检查，以及仍未运行的检查。
UI 路径文件全文包含 N02：
---
applyTo: "ui/**"
---
仅打开本地预览的控件应保留标签 `Open preview`。让独立的发送操作与它保持清晰区别。
解析器路径文件全文包含 N03：
---
applyTo: "parser/**"
---
保留 `read_rows` 契约：向调用方返回记录，将文件写入和网络操作放在该函数之外。
这里没有把任何命令列为已验证。N07 仍放在 evidence/commands-to-check.md 中，状态为 NOT_RUN，并注明缺少命令定义。后续任务可以检查实际项目，确定适当的检查方式，然后才将某条命令描述为已知可用。
在依赖这些指引前写出适用矩阵
这些笔记的预期适用范围如下：
| 正在处理的文件 | 仓库级指引 | 路径级指引 | 临时请求 |
|---|---|---|---|
ui/cards/note-card.tsx |
N01 | N02 | EXP-12 期间为 N04，COPY-13 期间为 N08 |
parser/readers/rows.py |
N01 | N03 | 两个 UI 任务均不适用 |
decisions/0001-parser-boundary.md |
N01 | 无 UI/parser 路径笔记 | 仅限实际更新这份记录的任务 |
UI 标签规则不应变成解析器行为。针对一个样本的观察不应变成任何路径的规则。旧实验也不应仅因后续任务仍能读取它的记录，就继续保持有效。
这份矩阵是编写者定义的适用约定，不是对平台匹配或指令执行情况的测试。如果任务涉及多个路径，平台可能提供多个区域的相关指引。应明确每条规则自身的对象，并核实实际平台支持的机制，而不是假设文件分开就能隔离所有上下文。
撤除临时规则，同时保留历史
假设一份不当的仓库级指引草稿累积了以下几行：
UI 工作始终使用紧凑布局。
始终丢弃空白行。
描述修改之前，始终运行 npm run check:board。
这些内容错误地提升了 N04、N06 和 N07 的地位。有用的清理历史应让纠正过程清晰可见：
| 步骤 | 拟议文档中发生的变化 | 仍然成立的事实 |
|---|---|---|
| H0 | 识别三条不当的长期指令 | 这是虚构的不当草稿，不是已安装的配置 |
| H1 | 将 N04 重新归为临时要求、N06 归为观察、N07 归为未检查项 | 它们原本的含义仍然可查 |
| H2 | 从长期指引中移除这些指令 | EXP-12 保留其任务笔记；E1 和命令提议保留各自的证据记录 |
| H3 | 关闭 EXP-12 | 紧凑布局不会作为默认值延续到后续工作 |
| H4 | 开启 COPY-13，将其文案提议与 N02 比较 | 在预期改动得到明确决定之前，Open preview 路径规则继续保留 |
不要为了让当前指引看起来一致而删除实验历史。保留任务记录，可以解释为何曾考虑紧凑版本，同时不会要求每个未来 UI 任务都采用它。
明确剩余的冲突
COPY-13 提议使用 Preview now，N02 则保留 Open preview。agent 应先指出这一冲突，再决定是否能将某个用语视为已经确定的新约定。有用的回应会说明受影响的控件，并询问当事人想做临时文案比较，还是长期变更。
不要凭空设立“最新消息总会覆盖路径文件”之类的通用规则。平台如何处理指令，以及当前人员的预期范围，都需要在各自的上下文中明确。这个示例没有为所有编码 agent 规定层级，也不暗示某项 CueSpec 功能。
第一步调查可以使用下面这份完整请求：
针对 COPY-13，研究 ui/cards/note-card.tsx 中仅涉及文案的提议：
Open preview -> Preview now。保留该操作的行为，并让发送操作保持独立。
这第一步不要编辑文件。
阅读适用的项目级/路径级指引。找出 N02 中既有的 Open preview 规则，
并报告冲突。询问这是临时比较还是长期标签变更；不要靠猜测指令
优先级作决定。
不要把 EXP-12 的紧凑/宽布局实验带入这项任务。将 E1 视为原因未知的
示例观察，而不是空白行要求。将 npm run check:board 视为尚未验证的
提议，而不是已经检查过的命令。
提出指引文件修改之前，核实所选平台/功能支持仓库级与路径级机制，
并说明其预期匹配范围。如果它与 GitHub 示例不同，解释差异。
返回适用笔记映射、单个控件的文案提议、尚未解决的决定，以及依据
实际项目制定的验证计划。
本次调查步骤不安装包、不执行项目、不修改真实指引文件、不公开
发布，也不部署。
GitHub 的任务建议 支持清楚描述问题与验收条件，并在实现前先做调查。这里的八条笔记分类和清理历史，是我们用来使请求更准确的具体方法。