创业团队做管理系统，别先堆页面：我把 14 个问题做成了需求门禁

摘要：页面清单不是需求契约。本文用一个正在运行的 Python 内容项目，演示如何把 14 个写前问题做成可阻断、可追踪、可复核的需求门禁。

如果你是创业团队的产品负责人，准备启动第一版管理系统，很可能见过这样的开工方式：先列登录页、首页、列表页、详情页，再继续补按钮和字段。页面清单越写越长，开发却仍然无法准确估时和报价。

这篇文章讨论的不是又一份需求文档模板，而是一个更具体的问题：管理系统需求怎么写，才能让不完整的输入先停下来？

我把白泽软件当前内容项目中的一次真实改造当作实验对象：先把写文章前必须回答的问题做成 JSON Brief，再让命令行执行写前阻断；成稿后，系统逐项寻找正文证据，并把检查结果与文件哈希绑定。这里有真实代码和测试，但它不是客户项目的效果背书，也没有虚构上线数据。

问题不在页面，而在输入没有契约

页面原型能说明界面大致长什么样，却很难独立回答这些问题：谁在什么场景下使用？现在的损失是什么？什么结果才算解决？哪些证据能支持判断？谁来验收？

当这些答案只散落在聊天记录、会议记忆和页面备注里，真正的问题是：输入没有形成可验证的决策契约。团队继续开工，常见代价就是返工、延期和错误报价。

页面清单和需求契约并不互斥。前者适合表达交互，后者负责约束决策。顺序应该是先说清用户、问题、结果和验收，再决定需要哪些页面，而不是从页面数量反推需求已经成熟。

这也解释了为什么只问"做几个页面"很难得到可靠报价。开发成本通常由角色权限、状态流转、数据约束、外部系统、异常路径和验收口径共同决定，页面数只是其中一小部分。

先回答 14 个问题，再允许写需求

我把写前必须回答的核心问题压缩成 14 项。它们既可以用于文章，也可以迁移到小型管理系统的需求澄清：

核心读者或用户是谁？
什么事件让他现在必须处理这件事？
可以观察到的症状是什么？
症状背后的根因是什么？
不处理会造成什么成本或风险？
他真正想得到什么结果？
他正处于认知、比较还是决策阶段？
新手和专业人员分别会怎样搜索这个问题？
需求对应哪条业务线？
哪些证据支持我们的判断？
相比已有方案，这次增加了什么可验证价值？
标题或需求名称承诺解决什么？
完成后，使用者具体能做出什么判断？
唯一、低摩擦的下一步是什么？

这 14 项不是为了把文档写长，而是为了在方案比较阶段暴露缺口。比如"给员工做一个请假管理页面"只描述了方案；"门店主管无法在排班前确认缺岗风险，需要在审批完成后自动更新当日可用人力，并由排班记录验收"才开始接近可验证需求。

GOV.UK 的服务设计指南强调，用户需要应建立在研究证据上，并用用户的问题和结果表达，而不是预设解决方案。这一点放到创业团队同样适用：问题清单只能逼你承认证据缺失，不能替你编造答案。

因此，Brief 还要有三个硬条件：未知项必须显式记录，涉及隐私的数据必须先处理，证据至少同时包含一手或项目事实与官方或原始资料。目标不是"每格都填字"，而是开工前得到一份可验证的需求契约。

把 Brief 做成可阻断的 JSON 契约

Markdown 表格方便阅读，却不适合做稳定门禁：字段可以随意改名，必填项容易被空话绕过，后续程序也很难准确消费。为此，我在当前 Python 项目中增加了版本化的 ArticleBrief 领域模型和应用服务。

下面是实际实现的核心路径，省略了错误对象的展示细节，但保留了真实控制逻辑：

python 复制代码

def check_brief(self, brief_path: Path) -> dict[str, Any]:
    self._load_spec()
    payload, raw = _read_json(brief_path)
    brief = parse_article_brief(payload)
    issues = validate_article_brief(payload, brief)
    return {
        "passed": not issues,
        "briefSha256": hashlib.sha256(raw).hexdigest(),
        "coreQuestionCount": len(CORE_QUESTION_IDS),
        "answeredQuestionCount": len(brief.acceptance_criteria),
    }

初始化命令只创建 prewrite-brief.json，不会提前创建正文。Brief 处于 draft、14 项不完整、证据不足、存在未解决隐私风险或未知项时，检查返回失败；只有状态切到 ready_to_write 且所有规则通过，正文入口才继续。

这里借鉴了两类成熟机制：

GitHub Issue Forms允许定义输入类型、校验和必填字段，说明协作输入可以从自由文本升级为结构化契约。
JSON Schema 对象规范可以约束属性、必填字段及额外字段，适合让不同工具围绕同一版本交换数据。

我们的结构化 Brief 验收标准不是"JSON 能解析"这么简单。它还检查受众是否属于白泽软件服务的中小企业、个人或创业团队，主题是否映射企业官网、小程序、App、管理系统或小游戏，证据类型是否满足要求，以及 C01 到 C14 是否恰好各出现一次。

写完之后，再逐项找正文证据

写前通过，不代表成稿兑现了承诺。最容易发生的偏差是：Brief 里写了目标用户、成本和行动，正文写着写着却只剩技术实现。

所以第二道门禁不是重新"读一遍感觉不错"，而是做写后覆盖审计。每个核心问题都要在 Brief 中声明可搜索的正文信号。例如本篇的 C11 同时要求出现"写前阻断"和"写后覆盖审计"；少任意一个，整篇都不能通过。

审计过程还会检查标题、指定章节、图片数量和条件化代码要求，随后生成类似下面的结果：

json 复制代码

{
  "passed": true,
  "problemChecklistResolved": true,
  "coreQuestionCount": 14,
  "coveredQuestionCount": 14,
  "briefSha256": "...",
  "articleSha256": "..."
}

两个 SHA-256 很重要。以后正文被改动，即使文件名不变，也不能继续拿旧报告证明新正文通过。报告只对当时那份 Brief 和那份文章负责。

覆盖审计也故意保持朴素：它不判断文风是否优美，只回答"承诺的内容有没有证据"。内容质量仍由另一道文章门禁检查，包括可见字数、图片、摘要、标签、代码块和明显的营销或模板化表述。

这套方法怎样迁移到管理系统项目

把文章领域替换为管理系统，14 项可以落成五组输入：

输入组	需要说清的内容	可以留下的验收证据
用户与场景	角色、权限、触发事件、当前操作路径	访谈记录、现状流程、权限矩阵
问题与成本	可观察症状、根因假设、业务损失	错误记录、耗时数据、异常样本
结果与边界	目标状态、包含项、不包含项	范围清单、状态机、接口边界
可信度	事实来源、未知项、隐私风险	数据样本、官方规则、风险清单
验收与行动	每项需求怎样证明完成、下一决策是什么	测试场景、验收人、可回放结果

假设一个创业团队要做库存管理系统，只写"商品、入库、出库、报表四个模块"仍然不能判断是否可以开发。继续追问后，需求可能变成：仓库管理员扫码提交出库；库存不足时禁止出库并保留失败记录；财务只能查看已确认流水；负责人以指定日期范围内的账实差异作为验收证据。

这时，页面还是那几页，但报价所需的关键信息已经不同：角色权限、库存状态、并发扣减、异常留痕和报表口径都被暴露出来了。开发团队可以据此拆任务、识别风险，也可以明确拒绝仍然缺证据的部分。

同类需求文章通常会提醒功能边界、非功能要求和验收流程，这些内容有价值。本次增加的不是另一张更长的检查表，而是把 14 个问题做成需求门禁：输入可被程序拒绝，输出可以逐项追踪，证据还能绑定具体版本。

边界：门禁不能代替用户研究

这套机制有四个明确边界。

第一，字段完整不等于事实正确。如果用户角色和痛点来自团队想象，JSON 再规范也只是把假设写得更整齐。

第二，关键词出现不等于内容真的有说服力。写后审计能发现遗漏，不能代替同行评审、用户试读和业务验收。

第三，不同项目需要条件问题。涉及支付、定位、医疗、未成年人、平台审核或外部接口时，应追加安全、合规和依赖问题，不能把 14 项当成全部答案。

第四，门禁应当允许诚实的"不知道"。未知项进入研究队列，比为了通过检查而伪造结论更安全。确认后再提升 Brief 修订号并重新校验。

下一步：拿一个真实需求跑一遍

先不要重写整个需求流程。拿一个真实需求跑一遍：让产品、业务和开发共同回答 14 项，为每项写出证据或明确标记未知；只有全部核心项可验证时，才进入原型、估时和开发。

跑完后，你应该能判断一个需求是否已经可以进入开发。如果仍然不能，最有价值的产出不是更多页面，而是一张明确写着"缺什么证据、由谁确认、何时再决策"的阻断清单。

这也是白泽软件在管理系统需求分析中采用这类门禁的原因：先减少错误理解，再讨论功能数量。它不会消除变化，但能让变化有来源、有版本、有验收依据。

标签: Python / 软件工程 / 需求分析