jumibot/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 代表專案自身文件），並附上來源、連結和審查日期。

可選章節

• 宗旨與價值觀（使命、願景和價值觀），放在開頭，可自成一個章節或作為第一個章節內的卡片。適用於旨在凝聚團隊或協作者的專案。
• 問題成本，當涉及經濟層面時：記錄在案的案例，附上其數據和「影響與範圍」、可避免的後果以及經濟模型（一個公式）。放在開發理由之後。
• 市場或領域規模評估：來源允許和支持的主張以及不支持的主張，需要哪些數據（分母、風險暴露、經濟學）、一個透明的場景（可能包含一個自訂計算器）以及如何將其轉化為可辯護的估算。放在「須證明事項」之前。
• 與現有參考的比較附錄：每個面向一張卡片，包含兩欄（「參考 · 已發表」和「專案 · 設計」）以及每種方法的貢獻。最後，列出比較應保留的價值觀以及如何檢查附加價值。
• 元素規格表附錄（藥品、材料、組件、典型客戶……）：每個元素一個規格表，包含其數據和場景。產生器會添加一個搜尋器和場景篩選器。
• 影響：如果產品成功，會帶來什麼改變，附帶條件是取決於試行專案的證明結果。每個面向一張卡片（經濟、對人群、對領域或環境），包含「可能改變什麼」及其 指標，需可前後測量。開場散文應說明已存在的基線以及尚待衡量的部分；未經此對比，任何節省金額都不能歸因於專案。如果引用 SDGs，需使用其官方名稱和來源。放在問題成本或需求章節之後。
• 風險：可能出錯的地方以及如何緩解。每個風險一張卡片，附有標籤指明其類別（技術、運營、經濟、法規）、「緩解措施」和「在何處驗證」，後者指向「須證明事項」中的某個階段或關卡。開場散文應說明主要風險以及計劃如何及早發現它。尚未分析的部分（例如法規遵循）應宣告為開放性風險，並在可能時附上來源。緊接在「須證明事項」之前。
• 合作邀請：尋找何種人才、提供什麼以及期望什麼。適用於要分享的文件。

分層閱讀。 先傳達最重要的資訊，後續每一層則深入探討：只閱讀第一層的人能掌握精華，想了解更多的人則繼續閱讀。順序基於重要性，而非得出結論的過程。這適用於整份文件以及每個章節：每個章節以其結論開頭（參閱「寫作規則」），並將細節留給卡片、可折疊的 #### 章節和附錄。

如果專案需要此處未列出的章節，應先向作者提議再撰寫。如果該章節對其他專案也有用，則是對此技能（屬於 SF）的改進：不應記錄在專案中，僅需在該技能中一行說明；在 SF 內部，它則屬於該專案。

寫作規則

• 僅記錄最終決策。 文件描述當前狀態，不包含歷史紀錄。
• 三種陳述類型，始終區分：已發表的事實（附參考）、專案的設計目標（希望實現的功能）以及計算假設（標記為說明性質）。文件開頭的範圍提示框應說明此區分，而在需要比較的地方，應使用「已發表」和「設計」標籤提醒讀者。
• 領域中的每個數字或陳述在寫入前都必須查證來源，絕不憑記憶，並在同一句子中附上參考。如需搜尋網路，若未獲作者許可，應先請求許可。
• 每項證據也必須說明其不支持的內容。 「對專案的解讀」、「論證的限制」、「影響與範圍」：文件在標示自身限制時更能獲得信賴。
• 精簡。 段落由兩到三個句子組成，每個句子約 20 個單詞或更少，首次出現的縮寫需說明全稱。核心內容應一氣呵成；詳細內容則放入附錄。
• 無廢話。 不要提及文件本身（「必須更新此文件…」、「此文件不包含…」）或顯而易見的事實：每個句子都應為專案貢獻資訊。
• 每個章節都用論證性散文開頭，就像第一章節一樣：在卡片之前且無副標題，大約兩到三個段落，包含章節的結論、支持它的事實（附上數據和參考），以及尚待確認的資訊。僅以一句介紹句是不夠的。論點或整體解讀應放在該散文中，而非提示框。卡片隨後提供可供查閱的細節，但不重複論點。
• 使用完整句子，而非清單。 在每個小節 (###) 內，使用帶有動詞的句子來解釋某事物如何運作以及原因，而不是無動詞的列舉。小節的標題應基於其回答的問題（例如「如何保持冷卻」），而非「主題：子主題」的模式，也不應將段落拆分為多個 #### 部分：#### 保留用於可折疊的細節。
• 結構可視，不中斷閱讀：何時使用卡片、散文、小節、提示框、表格或清單、粗體、重複欄位和排版，請參閱 crear_documentos 的「何時使用每種資源」。在奠基文件中，典型的卡片包括經驗、場景、證據、階段、關卡、比較面向、規格表以及產品的關鍵數據；在摘要中，成功的部分用散文描述，缺點則以表格列出問題及其狀態。
• 不使用讀者尚未知道的代碼。 內部代碼（S1， S2……）僅在定義它們的章節之後使用，並且有助於交叉引用時才使用。在此之前，以及在論證性散文中，應使用文字描述。
• 每項關鍵陳述都應在同一位置論證。 一個重要的論點或結論必須說明其依據（文件中的事實，附上數據和參考）以及尚未證明的部分。
• 提出建議，而非強制要求。 使用「建議」、「供評估」、「由相關人員決定」等用語。
• 尊重領域的敏感性。 專案領域的規則存在於其身分識別的 reglas 中（與 documento_vision 使用的規則相同）。

工作方式

1. 在提出前先閱讀：專案的願景、身分識別及其規則、現有的規格文件、代碼（如果可提供數據）或數位孿生，以及作者提供的資料。 盤點專案的所有論點。 產品的奠基文件應收集專案擁有的所有論點，特別是在與其他產品比較時：包括其他奠基文件中的論點、願景文件、規格文件以及已建構的成果（數位孿生、原型、測試）。在撰寫或審查前，應先盤點缺失的項目，包含其來源和類別（已發表事實、設計目標、假設或僅在模擬中驗證的進度），以及文件間相互矛盾的內容，這些應在傳遞任何受影響的數據之前詢問作者。對於已建構的成果，應說明其已宣告的限制。
2. 提議目錄和工具：詢問文件是為專案本身還是為使用者製作，以及需要哪些工具（搜尋器、註記、「閱讀」、折疊、圖例、編輯……），並針對該用途提出建議，以單一問題提供選項；將答案記錄在頁首。提議目錄：核心章節、適用的可選章節及其理由、候選場景及其代碼以及封面數據。讓作者先進行調整，然後再撰寫。
3. 調查缺失的證據（獲得搜索許可後），附上確切來源。
4. 撰寫 .md 文件，使用下方資源，然後產生 .html 檔案。在取代舊版本前，先在 _respaldo/ 目錄中備份（crear_documentos， 「備份」）。
5. 驗證（參閱「檢查」）並提供摘要：內容包含什麼、哪些內容是說明性質、缺少哪些證據以及哪些部分適合由專家驗證。
6. 與作者一同調整。 每次一般性修正都應添加至其規則中。不應清除；每個版本都應保留。如果技能本身顯示有瑕疵或改進空間，應提出建議。