jumibot/documento_fundacional

奠基文档（Documento Fundacional）

奠基文档以正式且紧凑的形式呈现一个项目（或一个产品系列中的某个产品）：它满足何种需求、为何值得开发、它是什么、在哪些场景下能创造价值、有什么证据支撑，以及它需要证明什么。它是项目的参考性描述。

它与愿景文档（documento_vision 技能）有三点不同：

• 无叙述性历史。 没有案例、场景或序言。它像一份档案一样，是结构化的描述。
• 更加正式。 领域内的每一个论断都附有参考文献，并且始终明确区分哪些是已发表的事实，哪些是设计目标，哪些是计算假设。
• 既服务于作者，也便于分享。 它为作者（以及未来会话中的 Claude）提供一个紧凑且无干扰的描述，同时可以原样交付给协作者、合作伙伴或资助方。

两者相辅相成。愿景文档用故事讲述项目；奠基文档则对其进行描述。如果其中一个改变，另一个也需要随之审阅。

本技能说明奠基文档应包含什么内容以及如何撰写。生成器、资源及其语法、主题、工具和验证检查，均与 crear_documentos 技能共享，应结合该技能一同阅读。

存放位置

同一项目中的所有奠基文档应统一放置在 docs/specs/vision/ 目录下（遵循 SF 方法论中的“公共文档结构”）：包括愿景文档、奠基文档以及 infografias/ 目录下的技术信息图。

• 对于项目本身：docs/specs/vision/fundacional-<proyecto>.md 及其 .html 文件。
• 对于产品系列中的每个产品（如果适用）：fundacional-<producto>.md。

.md 文件是源文件。.html 文件由生成器生成，不得手动编辑。如果从一个现有的 PDF 或 HTML 文件开始工作，则应将其转换为 .md 格式，原始文件应保留在相同目录或 _respaldo/ 目录下。

范例。 如果项目已有一个符合这些规则的奠基文档，则在撰写或审阅另一个文档时，将其作为示例阅读；其特定领域的内容不应复制。

章节

每个奠基文档都包含一个核心章节，以及可选章节，当项目需要时才包含。章节按出现顺序编号。附录放在文档末尾，并带有标签“附录 A · …”。

顺序：先解释，后论证。 读者必须先了解产品是什么，然后才能评估论据。在开篇（如果有的话，包括目的、陈述开发理由的散文体引言，包含核心理念、差异点和论点）之后，是解释性章节：系统或产品系列、产品及其功能、场景和备选方案。然后是论证性章节：已记录的需求和问题成本、影响、规模评估、风险和“需要证明什么”。如果开篇已经总结了论点，那么关于已记录需求的信息卡片可以放在产品章节之后的独立章节中。

简约封面。 品牌、名称和标语使用普通字体（一行或两行）。仅此而已，以保持页眉低调：理念和目的作为开场白开启第一节，版本和状态放在页脚，没有数字行（统计卡片或证据数量是清单，而非论点；如果某个数字本身是论据，则应放在正文中）。

全局范围说明（说明文档中哪些部分是设计目标，哪些已得到验证，或适用于全文的任何标准）：应放在开头，在所有章节之外。使用引用 > 格式，位于 # 名称 和第一个 ## 之间；生成器会在章节之前将其放入一个框内。

核心章节

1. 开发理由。 以散文体引言开始，位于卡片之前且无副标题：

   • 核心理念和目的，作为开场白；
   • 差异性，与现有替代方案对比，一个段落，包含参考文献，每个替代方案一句话；
   • 开发论点：现在值得资助或构建什么，以及在什么条件下会具有价值。使用散文体，而非方框，并且必须论证：说明它基于文档中的哪些事实（附带具体数字和参考文献），以及尚待了解的内容，这也是试点需要衡量的内容。

   之后，放置两到三张关于已记录需求的信息卡片（测量到的问题、干预能力、后果），每张卡片附带参考文献。这种形式——论证性散文体后跟被论证的卡片——是所有章节的模板（参见“编辑规则”）。

2. 产品。 用少量数字简要说明是什么（能力、自主性、范围……）、如何按子系统工作、其架构、主要功能、如何演进（产品系列、平台、验证/重新配置/重新设计）以及它不做什么。

3. 使用场景。 产品可能创造价值的场景，每个场景带有一个代码（如 S1、S2……），以便在文档的其他部分引用。每个场景包含：何时创造价值、论据的局限性、衡量什么以及文档基础。场景之间是相互兼容的；不应将它们作为独立的群体进行累加。

4. 证据。 首先，说明搜索方法和范围。然后，按每项证据一张卡片：类型（测量、试点、指南、研究……）、说明了什么（含具体数字）、影响哪些场景，以及对项目的启示，说明其支持什么以及不支持什么。

5. 需要证明什么。 从文档到试点的步骤：按优先级排序的阶段，每个阶段包含其回路、理由和推进条件；所需的验证（技术、运营、经济）；推进决策（关卡）；建议的决策以及如何衡量。

6. 来源与参考文献。 所有来源按类型编码（例如：E 代表证据，F 代表技术数据表，P 代表价格，D 代表经济数据，C 代表临床数据，M 代表项目自己的文档），包括出处、链接和审阅日期。

可选章节

• 目的与价值观（使命、愿景和价值观），放在开头，作为独立章节或作为第一节中的信息卡片。适用于旨在统一团队或协作者的项目。
• 问题成本，当有经济维度时：记录在案的案例（含具体数字和“影响与范围”）、可以避免什么以及经济模型（一个公式）。放在开发理由之后。
• 市场或领域规模评估：来源能够支持哪些论断、不能支持哪些论断，需要哪些数据（分母、暴露程度、经济数据），一个透明的场景（可能包含自有的计算器组件），以及如何将其转化为可行的估算。放在“需要证明什么”之前。
• 与现有参考方案的比较附录：每个维度一张卡片，两列（“参考方案·已发表”和“项目·设计”），以及每个方法的价值。最后是比较中应保持的值以及如何验证附加值。
• 按要素（药品、材料、组件、典型客户……）划分的数据表附录：每个要素一张数据表，包含其数据和场景。生成器会添加搜索框和按场景筛选的功能。
• 影响：如果产品有效，会改变什么，始终以试点证明的内容为前提。每个维度（经济、人员、地区或环境）一张卡片，包含“可能改变什么”及其指标，可在前后测量。开头的散文体应指出已经存在的基线以及尚待测量的内容；没有这种对比，任何节约数字都不能归于项目。如果引用可持续发展目标，应使用其官方名称和来源。放在问题成本或需求章节之后。
• 风险：可能出什么问题以及如何缓解。每项风险一张卡片，带有类别标签（技术、运营、经济、监管），“缓解措施”和“在哪里验证”，指向“需要证明什么”中的一个阶段或关卡。开头的散文体说明主要风险以及计划如何及早发现它。尚未分析的内容（例如监管契合度）应声明为未解决的风险，如有来源则一并提出。紧靠在“需要证明什么”之前。
• 合作邀请：寻找哪些角色，提供什么，期望什么。适用于需要共享的文档。

分层阅读。 最重要的信息优先传达，每一层进一步深化：只读第一层的人能把握核心内容，想要更多细节的人可以继续阅读。顺序按重要性，而非得出结论的过程。这适用于整个文档和每个章节：章节以其结论开头（参见“编辑规则”），详细信息则放在信息卡片、可折叠的 #### 和附录中。

如果项目需要一个此处未列出的章节，应在撰写前向作者提出建议。如果该章节对其他项目也很有用，那么这是对本技能的改进，属于 SF 范畴：不应记录在项目文档中，而应一句话说明即可；在 SF 内部，它属于项目范畴。

编辑规则

• 仅保留最终决策。 文档描述当前状态，不包含历史记录。
• 三类论断，始终分开：已发表的事实（带参考文献）、项目的设计目标（希望它达到什么效果）和计算假设（标记为说明性的）。开头的范围说明框会解释这一点，在需要比较的地方，会使用“已发表”和“设计”标签来提醒。
• 所有领域内的数字或论断，在撰写前必须对照来源进行核实，绝不能凭记忆，并且必须在其出现的同一个句子中附带参考文献。如需上网搜索，若作者尚未授权，则需先请求许可。
• 每项证据也必须说明其不能证明什么。 “对项目的启示”、“论据的局限性”、“影响与范围”：文档在指出自身局限性时会增加可信度。
• 紧凑。 段落由两到三句话组成，句子长度控制在 20 个单词以内，缩写在首次出现时需解释。核心部分应一口气读完；扩展的详细信息放在附录中。
• 无废话。 不要提及文档本身（如“本文档需要更新……”，“本文档不包含……”）或显而易见的废话：每个句子都为项目贡献价值。
• 每个章节都以论证性散文开头，就像第一章一样：在放置任何卡片和副标题之前，用大约两到三个段落，给出章节的结论、支持结论的事实（含数字和参考文献）、以及尚待了解的内容。一个如“六个经验允许……”这样的介绍性句子是不够的。论点或整体解读应放在这段散文中，而不是方框里。卡片放置其后，提供可供查阅的详细信息，但不得重复论点。
• 使用完整句子，而非清单体。 在每个小章节（###）内，应使用带动词的完整句子来解释某物是如何工作的以及为什么，而不是使用不带动词的列举（如“标识、库存、追溯……”）。小章节的标题应回答一个核心问题（例如“如何保持低温”），而不是使用“主题：子主题”的格式，并且不应将段落内容切成多个 #### 部分：#### 保留用于可折叠的细节内容。
• 结构要可见，但不要打断阅读流程： 何时使用卡片、散文、小章节、方框、表格或列表，以及粗体、重复字段和排版等细节，请参见 crear_documentos 技能中的“何时使用每种资源”。在奠基文档中，典型的信息卡片包括体验、场景、证据、阶段、关卡、比较维度、数据表和产品关键指标；在回顾分析中，成功之处用散文叙述，不足之处则用包含问题和相应状态的表格来呈现。
• 不引入读者尚不了解的代码。 内部代码（如 S1、S2……）仅在其定义的章节之后使用，并且仅在有助于交叉引用时才使用。在此之前，以及在论证性散文中，应使用文字描述（如“送货上门和家庭保存”）。
• 所有关键论断必须在其出现的位置得到论证。 一个重要的论点或结论应说明其依据（文档中的事实，含数字和参考文献）以及尚未被证明的内容。
• 提出建议，而非强制要求。 使用“建议”、“可供评估”、“由相关负责人决定”等措辞。
• 尊重领域内的敏感性。 项目领域的具体规则存在于其身份（reglas）文件中（与 documento_vision 读取的文件相同）。

工作流程

1. 在提出之前先阅读：项目的愿景文档、其身份和规则、如果存在的规范文档、能提供数据的代码或数字孪生体，以及作者带来的材料。 清单化项目的所有论据。 一个产品奠基文档应收集项目所有的论据，尤其是在与其他产品进行比较时，包括来自其他奠基文档、愿景文档、规范文档以及已构建内容（数字孪生体、原型、测试）的论据。在撰写或审阅之前，制作一个缺失内容的清单，包括其来源和类别（已发表事实、设计目标、假设或仅在仿真中验证的进展），以及文档之间的矛盾之处，这些问题必须在通过任何受影响的数据之前向作者提出询问。已构建的内容应以其申明的局限性来表述。
2. 提议目录和工具：询问文档是项目内部构件还是面向用户，以及需要哪些工具（搜索、注释、“阅读”功能、折叠、图例、编辑……），给出针对该场景的建议，一次提问并附带选项；将回答记录在文件头部。提议目录：核心章节、适用的可选章节及其理由、候选场景及其代码、以及封面数据。让作者在撰写前进行细化。
3. 研究缺失的证据（需获得搜索许可），注明其确切来源。
4. 编写 .md 文件，使用下文提到的资源，并生成 .html 文件。在替换任何版本前，先备份到 _respaldo/ 目录（参见 crear_documentos 技能中的“备份”）。
5. 验证（参见“验证检查”），然后提交一份总结：包含哪些内容、哪些是说明性的、缺少哪些证据、以及建议由哪些领域专家进行验证。
6. 与作者一起细化。 每次重大修改都应记录在此文档中。