setup-context

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

setup-context

初始化项目上下文

Mục tiêu: giúp user tạo

BR-001

(

docs/business-requirement

UR-001

(

docs/user-requirement

FR-001

(

docs/functional-requirement

) qua một cuộc hội thoại tự nhiên về dự án họ muốn làm, thay vì bắt user tự viết đủ 3 tài liệu chuẩn từ đầu hoặc trả lời máy móc 3 câu hỏi cố định "WHY của bạn là gì?". Đây là bước đầu tiên khi chưa có BR/UR/FR nào trong dự án — Business Requirement là gốc, User Requirement và Functional Requirement sinh ra từ đó. WHY/WHO/WHAT ở đây là 3 nhóm nội dung nội bộ agent dùng để phân loại và điền đúng tài liệu — không phải kịch bản câu hỏi đọc nguyên văn cho user.

目标：帮助用户通过关于其待开发项目的自然对话，生成

BR-001

（对应

docs/business-requirement

）、

UR-001

（对应

docs/user-requirement

）、

FR-001

（对应

docs/functional-requirement

），而非要求用户从头撰写完整的3份标准文档，或机械回答固定的3个问题“你的WHY是什么？”。这是项目中尚未有任何BR/UR/FR时的第一步——Business Requirement（业务需求）是核心，User Requirement（用户需求）和Functional Requirement（功能需求）均衍生于此。此处的WHY/WHO/WHAT是agent用于分类并填充对应文档的3个内部内容分组——并非要直接照搬原文向用户提问的脚本。

Tài liệu tham khảo thêm

参考文档

examples.md — 5 tình huống ĐÚNG/SAI cụ thể (few-shot): câu hỏi mở đầu, câu trả lời đã chứa sẵn nhiều khía cạnh, câu trả lời mơ hồ cần brainstorm, hỏi MoSCoW, và ranh giới WHAT (kết quả) vs HOW (cách hiện thực) khi viết FR. Đọc file này khi cần hình dung cụ thể cách diễn đạt câu hỏi/nội dung — không phải quy tắc bắt buộc, các quy tắc bắt buộc nằm ở phần dưới đây.

examples.md — 5个具体的正确/错误场景（few-shot示例）：开场提问、已涵盖多维度的回答、模糊回答需头脑风暴、询问MoSCoW优先级、以及撰写FR时WHAT（结果）与HOW（实现方式）的边界。当需要具象化提问/内容的表达形式时阅读此文件——这并非强制规则，强制规则位于下方章节。

Điều kiện tiên quyết

前置条件

Template cần cho

glossary

/BR/UR/FR/OQ đi kèm sẵn trong thư mục

templates/

cạnh chính

SKILL.md

này — không cần cài/copy gì thêm để có chúng:

Tài liệu	Template đi kèm skill
`docs/spec-kit-conventions.md`	`templates/spec-kit-conventions.md`
`docs/glossary/glossary.md`	`templates/glossary-template.md`
`docs/business-requirement/BR-*.md`	`templates/BR-template.md`
`docs/user-requirement/UR-*.md`	`templates/UR-template.md`
`docs/functional-requirement/FR-*.md`	`templates/FR-template.md`
`docs/meetings/open-questions/OQ-*.md`	`templates/OQ-template.md`
`docs/meetings/notes/MEET-*.md`	`templates/MEET-template.md`

Quy tắc chọn nguồn template — áp dụng ở mọi bước "Quy trình" bên dưới cần tạo file mới: ưu tiên

docs/<tầng>/<PREFIX>-template.md

(ví dụ

docs/glossary/glossary-template.md

docs/business-requirement/BR-template.md

) nếu dự án đã có sẵn (ví dụ do team tự tuỳ biến, hoặc do dự án đã scaffold đầy đủ bằng cách khác); chỉ dùng bản

templates/<tên>-template.md

đi kèm skill này khi dự án chưa có file template tương ứng — lúc đó tự tạo thư mục

docs/<tầng>/

trước rồi copy nguyên trạng bản đi kèm skill vào đúng vị trí (cùng tên file), giống hệt cách bước 1 dưới đây scaffold

glossary.md

. Không tự bịa cấu trúc/tên field khác ngoài 2 nguồn này.

docs/spec-kit-conventions.md

dùng đúng quy tắc trên: kiểm tồn tại chưa trước cả bước 1, nếu chưa có thì copy nguyên trạng từ

templates/spec-kit-conventions.md

(không hỏi user, không tạo subfolder — file nằm ngay

docs/

). File này chứa quy tắc cốt lõi dùng xuyên suốt Spec Kit (naming convention, vòng đời

status

, glossary-link theo độ sâu thư mục, ma trận lan truyền thay đổi...) — cũng đã được tóm tắt trực tiếp trong các mục dưới đây, đọc

docs/spec-kit-conventions.md

khi cần chi tiết hơn.

glossary

/BR/UR/FR/OQ对应的模板需预先放置在与本

SKILL.md

同级的

templates/

目录中——无需额外安装/复制即可使用：

文档	Skill附带的模板
`docs/spec-kit-conventions.md`	`templates/spec-kit-conventions.md`
`docs/glossary/glossary.md`	`templates/glossary-template.md`
`docs/business-requirement/BR-*.md`	`templates/BR-template.md`
`docs/user-requirement/UR-*.md`	`templates/UR-template.md`
`docs/functional-requirement/FR-*.md`	`templates/FR-template.md`
`docs/meetings/open-questions/OQ-*.md`	`templates/OQ-template.md`
`docs/meetings/notes/MEET-*.md`	`templates/MEET-template.md`

模板源选择规则 — 适用于下方“流程”中所有需要创建新文件的步骤： 如果项目已存在

docs/<层级>/<前缀>-template.md

（例如

docs/glossary/glossary-template.md

、

docs/business-requirement/BR-template.md

），则优先使用该模板（例如由团队自定义，或通过其他方式完整搭建的项目）；仅当项目不存在对应文件模板时，才使用本skill附带的

templates/<名称>-template.md

——此时需先创建

docs/<层级>/

目录，再将skill附带的模板原封不动复制到正确位置（文件名保持一致），与下方步骤1中搭建

glossary.md

的方式完全相同。不得自行编造除上述两个来源之外的结构/字段名称。

docs/spec-kit-conventions.md

需遵循上述规则：在步骤1之前检查是否已存在，若不存在则直接从

templates/spec-kit-conventions.md

原封不动复制（无需询问用户，无需创建子文件夹——文件直接放在

docs/

目录下）。该文件包含Spec Kit全程使用的核心规则（命名规范、

status

生命周期、基于目录深度的术语表链接、变更传播矩阵……）——这些规则也已直接提炼在下方各章节中，如需详情请阅读

docs/spec-kit-conventions.md

。

Nguyên tắc khi chạy skill này

运行此skill的原则

Câu hỏi mở đầu bằng ngôn ngữ đời thường, không nhắc thuật ngữ WHY/WHO/WHAT. Hỏi user đang muốn xây dự án gì, theo cách một người bình thường mô tả ý tưởng của họ — không đọc lại 3 câu hỏi mẫu cố định như một bảng câu hỏi. Câu trả lời tự do có thể chứa cả 3 khía cạnh (động cơ, đối tượng dùng, kết quả cần đạt) trộn lẫn cùng lúc, hoặc chỉ 1-2 khía cạnh — agent tự nghe và phân loại nội dung vào đúng nhóm (bối cảnh/động cơ → BR, đối tượng+nhu cầu → UR, kết quả/chức năng → FR), không bắt user tự tách bạch.
Hỏi tiếp để lấp khoảng trống, bằng câu hỏi bám sát ngữ cảnh vừa nghe — không đọc lại câu hỏi mẫu. Sau câu hỏi mở, rà xem nhóm nào (động cơ/đối tượng/kết quả) còn thiếu hoặc còn mờ, rồi hỏi tiếp tự nhiên dựa trên chính những gì user vừa kể — ví dụ nếu user đã kể rõ ai dùng và họ cần gì nhưng chưa nói vì sao dự án cần tồn tại, hỏi tiếp kiểu "Điều gì khiến bạn muốn làm cái này ngay bây giờ? Nếu không làm thì sao?" thay vì hỏi máy móc "WHY của bạn là gì?". Một số câu hỏi (ví dụ MoSCoW cho từng nhu cầu — xem bước 4) vẫn cần hỏi tường minh vì không thể suy ra từ văn phong tự nhiên; những câu đó vẫn nên lồng vào mạch hội thoại, không đọc như đang điền form.
Hỏi từng câu một, đợi trả lời — không hỏi dồn nhiều câu cùng lúc trong 1 lượt.
Ghi thẳng vào file chính thức (BR/UR/FR) — không tạo file nháp trung gian. Trả lời tới đâu, tài liệu được tạo/cập nhật tới đó, tránh giữ hai bản.
Vẫn phải điền đủ frontmatter theo template của từng loại:
```
id
```
,
```
type
```
,
```
status: draft
```
,
```
version: 1
```
,
```
created
```
/
```
last_updated
```
(lấy ngày hiện tại), và
```
parent_*
```
nối UR-001 → BR-001, FR-001 → UR-001.
Câu trả lời còn sơ sài/chung chung → brainstorm rồi hỏi lại, đừng hỏi lại kiểu "bạn nói rõ hơn được không?". Dựa vào ngữ cảnh đã có (câu trả lời trước đó trong cùng phiên, glossary, loại dự án), chủ động đề xuất 2-4 khả năng cụ thể và hỏi user xác nhận/chọn/sửa — ví dụ: "Ý bạn có phải là X hay Y? Còn edge case Z thì sao?". Đây KHÔNG phải ngoại lệ cho nguyên tắc không bịa nội dung ở dưới — mọi khả năng brainstorm ra chỉ là câu hỏi gợi ý, CHỈ ghi vào tài liệu sau khi user xác nhận rõ ràng.
Nếu sau khi đã brainstorm/hỏi lại mà user vẫn chưa có câu trả lời rõ ràng cho một mục con trong template (ví dụ Success metrics, Edge cases), để nguyên placeholder gốc của template — không bịa nội dung, không tự suy diễn chi tiết user chưa cung cấp.
Phân biệt "chưa trả lời" với "đã từ chối đoán số/chi tiết". Khi user chủ động từ chối việc đoán một con số/ngưỡng/hành vi cụ thể (ví dụ "đừng tự đặt số nhé", "cái đó chưa biết, đừng đoán") — dù có gắn nhãn
```
[Agent đề xuất — cần PO xác nhận]
```
và tạo file mới từ
```
docs/meetings/open-questions/OQ-template.md
```
(đặt tên
```
OQ-xxx_<slug>.md
```
, cùng path
```
plan-backlog
```
dùng — không tự đoán path khác) cũng không được chèn bất kỳ con số/giá trị cụ thể nào vào tài liệu, kể cả một giá trị "tạm dùng" có gắn nhãn rõ ràng; để nguyên placeholder gốc của template + OQ mô tả rõ điều còn thiếu, không có con số nào trong nội dung chính thức. Khác với trường hợp user đơn giản là chưa trả lời (chưa được hỏi, hoặc đã hỏi nhưng chưa có câu trả lời) — trường hợp đó vẫn được đề xuất 1 giá trị cụ thể kèm nhãn
```
[Agent đề xuất — cần PO xác nhận]
```
như bình thường. Từ chối tường minh là tín hiệu mạnh hơn "chưa trả lời" — chèn số dù có nhãn vẫn là không tôn trọng đúng những gì user vừa nói.
Không tự set
```
status: approved
```
— skill chỉ tạo bản
```
draft
```
. Review/approve là bước riêng của user/team. Quy ước xuyên suốt kit này: tài liệu tầng sau (User Requirement từ Business Requirement, Functional Requirement từ User Requirement, System Overview từ Functional Requirement) chỉ được tạo khi tài liệu tầng trước đã
```
status: approved
```
— không nhảy cấp.
Nếu user có nhiều hơn 1 WHY/WHO/WHAT cần tách (ví dụ nhiều persona khác nhau → nhiều UR), tạo thêm
```
UR-002
```
,
```
UR-003
```
... theo đúng naming convention thay vì nhồi vào 1 file.
Khi viết nội dung BR/UR/FR, thuật ngữ đã có trong
```
docs/glossary/glossary.md
```
→ gắn link Markdown tới đúng mục ở lần xuất hiện đầu tiên trong tài liệu (xem
```
docs/spec-kit-conventions.md
```
mục 3).
Không nhắc tên mã container/hệ thống cụ thể (dạng slug kỹ thuật như
```
checkout-api
```
,
```
maintenance-mobile
```
) trong BR/UR/FR hay
```
glossary.md
```
— mã container chỉ được chốt ở Bước A (
```
c4-container.md
```
, xem skill
```
c4-model
```
), chưa tồn tại ở tầng này. Nếu cần nhắc tới 1 phần hệ thống trong BR/UR/FR/glossary, mô tả bằng chức năng/nghiệp vụ (ví dụ "ứng dụng di động cho kỹ thuật viên") thay vì tên mã kỹ thuật — tránh việc BR/glossary tham chiếu ngược tới 1 quyết định đặt tên chưa xảy ra, và tên mã đó sau này có thể đổi/tách khác với lúc viết BR.

开场提问使用日常语言，不得提及WHY/WHO/WHAT术语。 以普通人描述想法的方式询问用户想要开发的项目——不要像读问卷一样照搬3个固定示例问题。用户的自由回答可能同时包含3个维度（动机、目标用户、需达成的结果），或仅包含1-2个维度——agent需自动识别并将内容分类到对应分组（背景/动机→BR，目标用户+需求→UR，结果/功能→FR），无需要求用户自行拆分。
针对信息缺口进行跟进提问，提问需贴合当前对话语境——不得照搬示例问题。 开场提问后，检查哪些分组（动机/目标用户/结果）仍存在缺失或模糊之处，然后基于用户刚刚讲述的内容自然跟进提问——例如，如果用户已明确说明目标用户及其需求，但未提及项目存在的原因，应询问“是什么让你现在想要做这个项目？如果不做会有什么影响？”，而非机械提问“你的WHY是什么？”。部分问题（例如针对每个需求的MoSCoW优先级——见步骤4）仍需明确询问，因为无法从自然表述中推断；这些问题仍需融入对话流程，而非像填表单一样生硬提问。
一次只提一个问题，等待用户回答——不得一次性提出多个问题。
直接写入正式文件（BR/UR/FR）——不得创建中间草稿文件。用户回答到哪一步，就创建/更新到哪一步，避免同时保留两份内容。
仍需按照各类模板填写完整的frontmatter：
```
id
```
、
```
type
```
、
```
status: draft
```
、
```
version: 1
```
、
```
created
```
/
```
last_updated
```
（取当前日期），以及用于关联的
```
parent_*
```
字段，将UR-001关联到BR-001，FR-001关联到UR-001。
若回答过于粗略/笼统→先进行头脑风暴再跟进提问，不要问“你能说得更清楚吗？”。 基于已有语境（同一会话中的先前回答、术语表、项目类型），主动提出2-4个具体可能性并请用户确认/选择/修改——例如：“你指的是X还是Y？那边缘场景Z呢？”。这并非下文“不得编造内容”原则的例外——所有头脑风暴得出的可能性仅作为提示性问题，仅在用户明确确认后方可写入文档。
若经过头脑风暴/跟进提问后，用户仍无法针对模板中的某个子项（例如Success metrics、Edge cases）给出明确回答，则保留模板原有的占位符——不得编造内容，不得自行推断用户未提供的细节。
区分“未回答”与“拒绝猜测数字/细节”。 当用户主动拒绝猜测某个具体数字/阈值/行为（例如“不要随便填数字”“这个还不知道，别猜”）——即使添加
```
[Agent 建议 — 需PO确认]
```
标签并从
```
docs/meetings/open-questions/OQ-template.md
```
创建新文件（命名为
```
OQ-xxx_<slug>.md
```
，使用与
```
plan-backlog
```
相同的路径——不得自行猜测其他路径），也不得向文档中插入任何具体数字/值，即使是带有明确标签的“临时值”；需保留模板原有的占位符+OQ文件明确描述缺失内容，正式文档中不得出现任何数字。这与用户单纯未回答的情况不同（未被提问，或已提问但未给出回答）——后者仍可像往常一样建议一个具体值并添加
```
[Agent 建议 — 需PO确认]
```
标签。明确拒绝是比“未回答”更强的信号——即使添加标签也插入数字是不尊重用户刚刚表述的内容。
不得自行设置
```
status: approved
```
——此skill仅创建
```
draft
```
版本。审核/批准是用户/团队的独立步骤。本Kit的通用规则：后续层级的文档（由Business Requirement生成User Requirement、由User Requirement生成Functional Requirement、由Functional Requirement生成System Overview）仅可在前一层级文档已设置
```
status: approved
```
时创建——不得越级。
若用户有多个需拆分的WHY/WHO/WHAT（例如多个不同用户角色→多个UR），需按照命名规范创建
```
UR-002
```
、
```
UR-003
```
……而非合并到一个文件中。
撰写BR/UR/FR内容时，若
```
docs/glossary/glossary.md
```
中已存在对应术语→需在文档中首次出现该术语时添加指向对应条目的Markdown链接（详见
```
docs/spec-kit-conventions.md
```
第3节）。
不得在BR/UR/FR或
glossary.md
中提及具体的容器/系统代码名称（例如
```
checkout-api
```
、
```
maintenance-mobile
```
这类技术slug）——容器代码名称仅在步骤A（
```
c4-container.md
```
，详见
```
c4-model
```
skill）中确定，在当前层级尚未存在。若需在BR/UR/FR/术语表中提及系统的某一部分，需通过功能/业务描述（例如“面向技术人员的移动应用”）而非技术代码名称——避免BR/术语表引用尚未做出的命名决策，且代码名称后续可能与撰写BR时有所不同/拆分。

Quy trình

流程

Kiểm tra
```
docs/glossary/glossary.md
```
đã tồn tại chưa (
```
docs/spec-kit-conventions.md
```
, mục 2, nguyên tắc chung #1 bắt buộc đọc file này trước mọi tài liệu). Đây thường là task đầu tiên chạy trên 1 dự án mới nên file này nhiều khả năng chưa có — nếu chưa có, copy nguyên trạng template đúng theo quy tắc chọn nguồn ở "Điều kiện tiên quyết" (ưu tiên
```
docs/glossary/glossary-template.md
```
nếu dự án đã có, không thì dùng
```
templates/glossary-template.md
```
đi kèm skill này) thành
```
glossary.md
```
trước khi hỏi câu mở đầu, không hỏi user, không bỏ qua bước này. Nếu đã có, đọc qua để nắm thuật ngữ dự án hiện tại.
Kiểm tra
```
docs/business-requirement/
```
đã có file
```
BR-*
```
nào ngoài
```
BR-template.md
```
chưa. Nếu có, hỏi user muốn tạo BR mới hay tiếp tục/refine BR đang có — không tự ý ghi đè.
Hỏi mở đầu, 1 câu duy nhất, ngôn ngữ tự nhiên — ví dụ: "Kể tôi nghe về dự án bạn muốn làm — bạn đang hình dung xây cái gì, cho ai dùng, và điều gì khiến bạn muốn làm nó?". Không đọc nguyên văn 3 câu hỏi WHY/WHO/WHAT tách rời, không dùng thuật ngữ này khi hỏi user. Nếu câu trả lời còn chung chung/mơ hồ ngay từ đầu, brainstorm 2-4 hướng cụ thể rồi hỏi lại (xem nguyên tắc ở trên) trước khi đi tiếp.
Phân loại câu trả lời vừa nghe vào 3 nhóm nội bộ, rồi hỏi tiếp để lấp phần còn thiếu — mỗi câu hỏi tiếp theo bám vào chính những gì user vừa kể, không đọc lại câu hỏi mẫu:
- Động cơ/bối cảnh (→ BR, khái niệm WHY): vì sao dự án cần tồn tại, đang giải quyết vấn đề/nắm bắt cơ hội gì, không làm thì sao, cải thiện được gì (IMPROVE) và đánh đổi gì (COST). Nếu phần này còn thiếu/mờ sau câu hỏi mở, hỏi tiếp tự nhiên theo mạch chuyện (ví dụ dựa vào lý do user vừa nêu, hỏi sâu hơn về hệ quả nếu không làm). Khi đủ nội dung → tạo
```
docs/business-requirement/BR-001_<slug>.md
```
  từ template đúng theo quy tắc chọn nguồn ở "Điều kiện tiên quyết", điền "Bối cảnh (WHY)", "Mục tiêu kinh doanh", "Lợi ích & chi phí (IMPROVE/COST)".
- Đối tượng dùng + nhu cầu (→ UR, khái niệm WHO): ai dùng — persona nào, pain point hiện tại, nhu cầu cụ thể. Nếu còn thiếu/mờ, hỏi tiếp tự nhiên (ví dụ "Còn ai khác cũng dùng cái này không, hay chỉ mình họ?"). Khi đủ → tạo
```
docs/user-requirement/UR-001_<slug>.md
```
  , điền "Đối tượng người dùng (WHO)". Nếu user kể nhiều nhu cầu khác nhau trong cùng 1 UR (cùng 1 persona nhưng nhiều nhu cầu tách biệt) — điền mỗi nhu cầu 1 dòng riêng trong bảng "Nhu cầu người dùng & Ưu tiên", không gộp chung nhiều nhu cầu vào 1 dòng rồi dùng chung 1 mức ưu tiên (đây là lỗi thật đã xảy ra: 3 nhu cầu khác nhau bị gộp dưới 1 mức MoSCoW duy nhất).
```
parent_business_requirement: BR-001
```
  . Riêng mức ưu tiên luôn phải hỏi tường minh, không tự suy đoán từ văn phong, vì không thể rút ra từ cách user kể chuyện: "Nhu cầu này ở mức ưu tiên nào — Must have / Should have / Could have / Won't have (MoSCoW)?" hỏi riêng cho từng dòng nhu cầu, không hỏi 1 lần rồi áp dụng chung cho cả bảng. Đây là field bắt buộc trong
```
UR-template.md
```
  , không phải nội dung agent tự gán theo cảm nhận.
- Kết quả/chức năng cần đạt (→ FR, khái niệm WHAT): hệ thống cần đạt được kết quả/đầu ra gì để đáp ứng nhu cầu đó (mô tả ở mức kết quả cần đạt, chưa cần nói cách triển khai kỹ thuật — cách hiện thực sẽ quyết định ở System Overview/C4 và khi phân rã Epic/Feature/User Story), có business rule nào cần biết trước không. Nếu còn thiếu/mờ, hỏi tiếp tự nhiên. Khi đủ → tạo
```
docs/functional-requirement/FR-001_<slug>.md
```
  , điền "Mô tả chức năng (WHAT)", "Business rules",
```
parent_user_requirement: UR-001
```
  . Thứ tự hỏi-tiếp không bắt buộc theo đúng thứ tự BR→UR→FR ở trên nếu mạch hội thoại tự nhiên dẫn sang nhóm khác trước — miễn cuối cùng cả 3 nhóm đều đủ nội dung trước khi tạo file tương ứng (file vẫn phải tạo theo đúng thứ tự BR trước UR trước FR, vì UR/FR cần trỏ
```
parent_*
```
  về tài liệu đã tồn tại).
Cập nhật ngược mục "Liên kết" ở BR-001/UR-001 để trỏ xuôi tới UR-001/FR-001 vừa tạo. Trước khi coi bước này xong, kiểm lại 2 việc riêng biệt — cả 2 hay bị bỏ quên trong lúc tập trung viết nội dung, kiểm lại rõ ràng ở đây thay vì chỉ tin đã làm đúng lúc viết:
- Glossary link: liệt kê ra từng file BR/UR/FR đã tạo/sửa trong phiên (không chỉ file gần nhất đang nhớ — lỗi thật đã xảy ra: link đúng ở file đầu tiên mỗi tầng, bị quên hoàn toàn ở các file sau cùng tầng). Đọc lại thủ công không đủ tin cậy cho bước này (lỗi thật đã xảy ra ngay cả khi biết trước rủi ro và cố ý đọc lại cẩn thận): liệt kê toàn bộ thuật ngữ có trong
```
docs/glossary/glossary.md
```
  , rồi dùng công cụ tìm chuỗi sẵn có (search/grep trong môi trường đang chạy) quét từng file trong danh sách trên theo từng thuật ngữ đó, thay vì chỉ đọc mắt. Với từng file phát hiện thiếu, kiểm lại đúng lần xuất hiện đầu tiên trong thân bài có link chưa (xem nguyên tắc ở trên,
```
docs/spec-kit-conventions.md
```
  mục 3). Tìm thấy link chưa đủ — còn phải xác nhận link đó resolve đúng file, không chỉ "có xuất hiện" (lỗi thật đã xảy ra: 21/21 file sai độ sâu
```
../
```
  vẫn qua được checkpoint vì có link, chỉ trỏ sai chỗ): đếm số
```
../
```
  trong từng link tìm được có đúng 1 cấp không — BR/UR/FR nằm ngay trong
```
docs/<tầng>/
```
  , luôn đúng 1 cấp (
```
../glossary/glossary.md
```
  , xem bảng độ sâu mục 3); sai số cấp thì sửa lại link, không chỉ tính là "đã có link" rồi bỏ qua. Nếu file đó đã
  status: approved
  khi phát hiện thiếu link — đưa lại về
```
status: draft
```
  trước khi sửa (xem
```
docs/spec-kit-conventions.md
```
  mục 1: sửa nội dung tài liệu đã approved phải đưa lại draft để review lại), sửa xong mới cân nhắc approve lại; không sửa thẳng nội dung mà giữ nguyên
```
status: approved
```
  .
- Mỗi dòng nhu cầu trong bảng "Nhu cầu người dùng & Ưu tiên" của mọi UR đã tạo phải có ít nhất 1 FR trỏ
```
parent_user_requirement
```
  về đúng UR đó và cover đúng nhu cầu đó — liệt kê từng dòng nhu cầu, đối chiếu xem đã có FR nào cover chưa. Nhu cầu nào chưa có FR (lỗi thật đã xảy ra: 1/3 nhu cầu của 1 UR không có FR nào, chỉ phát hiện được khi đối chiếu ngược tới tận User Story) → tạo FR cho nhu cầu đó ngay trong phiên này trước khi coi bước WHAT là xong, không được bỏ sót rồi để tầng sau (Epic/Feature/US) tự phát hiện gap.
Trước khi kết thúc phiên, quét lại toàn bộ nội dung BR/UR/FR vừa viết trong phiên (không chỉ mục user vừa hỏi lại tường minh) — tìm mọi chi tiết cụ thể mà user chưa thực sự xác nhận, cả định lượng (con số, ngưỡng, success metric) lẫn định tính (business rule diễn đạt kiểu chắc chắn dù chỉ là suy đoán, hành vi lỗi cụ thể, MoSCoW tự gán thay vì hỏi — không chỉ quét chi tiết có số), kể cả chi tiết agent chèn thêm khi diễn giải lại câu trả lời chung chung của user. Với mỗi chi tiết như vậy: hỏi lại user, hoặc để nguyên placeholder gốc của template (xem nguyên tắc "không bịa nội dung" ở trên) — không chỉ dựa vào trí nhớ những chỗ agent tự thấy "cần chú ý" lúc viết, vì cùng 1 lượt suy luận vừa viết vừa tự rà thường bỏ sót đúng những chi tiết nó không nhớ là đã tự thêm vào. Nếu khả thi, chạy bước này như 1 lượt riêng sau khi đã viết xong toàn bộ, thay vì xen kẽ ngay trong lúc viết.
Nhắc user: review và set
```
status: approved
```
cho từng tầng trước khi tạo System Overview (C4 Context + Container Diagram).

检查
```
docs/glossary/glossary.md
```
是否已存在（
```
docs/spec-kit-conventions.md
```
第2节，通用原则#1要求在所有文档之前阅读此文件）。这通常是新项目上运行的首个任务，因此该文件很可能不存在——若不存在，需按照“前置条件”中的模板源选择规则，将对应模板原封不动复制为
```
glossary.md
```
（若项目已存在
```
docs/glossary/glossary-template.md
```
则优先使用，否则使用本skill附带的
```
templates/glossary-template.md
```
），然后再进行开场提问，无需询问用户，不得跳过此步骤。若已存在，则阅读该文件以了解当前项目的术语。
检查
```
docs/business-requirement/
```
目录中是否存在除
```
BR-template.md
```
之外的
```
BR-*
```
文件。若存在，询问用户是要创建新的BR还是继续完善现有BR——不得自行覆盖。
开场提问仅需一个自然语言问题——例如：“跟我讲讲你想要做的项目吧——你打算做什么、给谁用，以及为什么想要做这个项目？”。不得照搬拆分的3个WHY/WHO/WHAT问题原文，提问时不得使用这些术语。若用户的初始回答过于笼统/模糊，需先头脑风暴2-4个具体方向再跟进提问（详见上述原则），然后再继续下一步。
将用户刚刚的回答分类到3个内部分组，然后跟进提问填补缺失内容——每个后续提问需贴合用户刚刚讲述的内容，不得照搬示例问题：
- 动机/背景（→ BR，即WHY概念）： 项目为何存在，正在解决什么问题/抓住什么机遇，不做会有什么后果，能带来哪些改进（IMPROVE）和成本（COST）。若开场提问后该部分仍有缺失/模糊之处，需顺着对话自然跟进提问（例如基于用户刚刚提到的原因，深入询问不做的后果）。内容足够时→按照“前置条件”中的模板源选择规则，创建
```
docs/business-requirement/BR-001_<slug>.md
```
  ，填写“背景（WHY）”“业务目标”“收益与成本（IMPROVE/COST）”。
- 目标用户+需求（→ UR，即WHO概念）： 谁在使用——具体用户角色、当前痛点、具体需求。若仍有缺失/模糊之处，自然跟进提问（例如“还有其他人会用这个吗，还是只有他们？”）。内容足够时→创建
```
docs/user-requirement/UR-001_<slug>.md
```
  ，填写“目标用户（WHO）”。若用户在同一个UR中提及多个不同需求（同一用户角色但多个独立需求）——需在“用户需求与优先级”表格中每个需求单独占一行，不得将多个需求合并到一行并使用同一优先级（曾出现过此类错误：3个不同需求被合并到同一MoSCoW优先级下）。设置
```
parent_business_requirement: BR-001
```
  。优先级必须明确询问，不得从表述语气中推断，因为无法从用户的讲述方式中得出：“这个需求的优先级是哪一级——Must have / Should have / Could have / Won't have（MoSCoW）？”需针对每一行需求单独询问，不得一次性询问后统一应用到整个表格。这是
```
UR-template.md
```
  中的必填字段，不得由agent自行根据主观判断赋值。
- 需达成的结果/功能（→ FR，即WHAT概念）： 系统需达成哪些结果/输出以满足该需求（描述需聚焦于需达成的结果，无需提及技术实现方式——实现方式将在System Overview/C4以及拆分Epic/Feature/User Story时确定），是否有需提前了解的业务规则。若仍有缺失/模糊之处，自然跟进提问。内容足够时→创建
```
docs/functional-requirement/FR-001_<slug>.md
```
  ，填写“功能描述（WHAT）”“业务规则”，设置
```
parent_user_requirement: UR-001
```
  。若自然对话流程先导向其他分组，跟进提问的顺序无需严格遵循上述BR→UR→FR的顺序——只要最终在创建对应文件前3个分组的内容均已足够即可（文件仍需按照BR先于UR、UR先于FR的顺序创建，因为UR/FR需要通过
```
parent_*
```
  关联到已存在的文档）。
反向更新BR-001/UR-001中的“链接”部分，使其指向刚创建的UR-001/FR-001。在标记此步骤完成前，需单独检查两项内容——这两项内容在专注撰写内容时容易被遗漏，需在此处明确检查，而非仅依赖撰写时的记忆：
- 术语表链接：列出本次会话中创建/修改的所有BR/UR/FR文件（不仅是最近记得的文件——曾出现过此类错误：每层的第一个文件链接正确，但同层后续文件完全遗漏链接）。人工重读不足以确保此步骤的准确性（即使提前知晓风险并刻意仔细重读，仍曾出现过错误）：列出
```
docs/glossary/glossary.md
```
  中的所有术语，然后使用环境中自带的字符串搜索工具（search/grep）针对每个术语扫描上述列表中的每个文件，而非仅用肉眼阅读。对于每个发现缺失链接的文件，检查正文首次出现该术语时是否已添加链接（详见上述原则及
```
docs/spec-kit-conventions.md
```
  第3节）。找到链接还不够——需确认链接能正确指向对应文件，而非仅“存在链接”（曾出现过此类错误：21个文件的
```
../
```
  层级错误，但因存在链接而通过检查点，实际指向错误位置）：统计每个找到的链接中的
```
../
```
  数量是否为1级——BR/UR/FR直接位于
```
docs/<层级>/
```
  目录下，链接应始终为1级（
```
../glossary/glossary.md
```
  ，详见第3节的层级表）；若层级错误则修改链接，不得仅视为“已有链接”而忽略。若发现缺失链接时该文件已设置
```
status: approved
```
  ——需先将其改回
```
status: draft
```
  再进行修改（详见
```
docs/spec-kit-conventions.md
```
  第1节：修改已批准的文档内容需先改回草稿状态重新审核），修改完成后再考虑重新批准；不得直接修改内容却保留
```
status: approved
```
  。
- 每个已创建的UR中“用户需求与优先级”表格的每一行需求，必须至少有一个FR通过
```
parent_user_requirement
```
  关联到该UR并覆盖对应需求——列出每一行需求，核对是否已有对应的FR覆盖。若某需求尚未有FR（曾出现过此类错误：某UR的1/3需求无对应FR，直到反向核对到User Story时才发现）→需在本次会话中立即为该需求创建FR，再标记WHAT步骤完成，不得遗漏后交由后续层级（Epic/Feature/US）自行发现缺口。
在会话结束前，扫描本次会话中撰写的所有BR/UR/FR内容（不仅是用户明确询问的部分）——找出所有用户未真正确认的具体细节，包括定量细节（数字、阈值、成功指标）和定性细节（即使只是推断却被肯定表述的业务规则、具体错误行为、未询问就自行赋值的MoSCoW优先级——不仅扫描带数字的细节），包括agent在解读用户笼统回答时自行添加的细节。对于每个此类细节：需向用户确认，或保留模板原有的占位符（详见上述“不得编造内容”原则）——不得仅依赖agent撰写时自认为“需要注意”的记忆，因为同一思考过程中边写边自查往往会遗漏那些自己忘记是自行添加的细节。若可行，此步骤应在全部内容撰写完成后单独进行，而非穿插在撰写过程中。
提醒用户：在创建System Overview（C4 Context + Container Diagram）前，需审核并为每个层级的文档设置
```
status: approved
```
。