委託開發的規格書，維持 Excel 就好嗎 ── 作為交付物的格式選擇方式

「收到了修改後的規格書，卻搞不清楚哪裡改了，就這樣蓋了驗收章」

「想委託改修時才發現，交付的 Excel 規格書和現在的畫面完全對不上」

「開發公司交來了方格紙狀的 Excel 規格書，這樣正常嗎」

把系統開發委託給外部公司時，規格書・設計文件會和程式一起交付。在日本的委託開發中，這類文件非常多是用 Excel 製作，而且經常採用被稱為「Excel 方格紙」的寫法──把儲存格切得很細，當成稿紙一樣使用。

網路上對 Excel 方格紙的批評並不少見，但大多數討論的是它作為開發團隊內部文件時有多難用。本文換一個角度，把焦點收窄到委託開發中交付給客戶的規格書，用驗收・規格變更・維護這些合約實務的語言，整理問題究竟出在哪裡、又該選擇怎樣的格式。希望內容對發包方，以及交付方的開發公司都有幫助。

1. 先講結論

先把要點彙整一下。

• 交付的規格書該用什麼格式，不應看「開發過程中是否好寫」，而應看「顧客能否審閱」「能否經得起驗收」「能否共享規格變更的差異」「數年後維護時是否還能用」來選擇
• 結論不是「捨棄 Excel」，而是「捨棄方格紙，回歸適得其所」。文章用 Word，表格用 Excel 本來的表格，圖用作圖工具，合意的記錄用 PDF
• 在討論格式之前，應先在合約中(個別合約對交付物的明確約定)決定哪些文件屬於成果物・是否能拿到可編輯的原本

把依文件性質劃分的推薦格式整理成判斷表，如下所示。

以下依序說明為什麼會得出這樣的結論。

2. 作為交付物的 Excel 方格紙規格書，問題出在哪裡

首先要說明一點，問題並不在於 Excel 這款軟體本身。作為試算表・一覽表的工具，Excel 相當優秀，正如後文所述，在項目定義文件等場景中，Excel 正是正確答案。問題在於，把文章、圖、表格這些性質各不相同的東西，全都塞進了「方格紙」裡。

如果只是公司內部文件，這不過是「寫的人自己覺得麻煩」的問題。但一旦成為交付物，情況就不同了。因為規格書是顧客支付對價換取的成果物，是驗收的對象，也是此後要使用多年的資產。從交付物的角度來看，Excel 方格紙存在以下問題。

2.1 驗收階段無法充分審閱

Excel 方格紙沒有像 Word 追蹤修訂那樣實用的差異顯示機制。準確地說，Microsoft 365 的共同編輯環境中確實有儲存格變更歷程記錄(「顯示變更內容」及版本歷程記錄)，也存在 Spreadsheet Compare 這類用來比較活頁簿的工具。但能追蹤的主要是儲存格的值與公式，方格紙文件大量使用的圖案・文字方塊中的文字並不在追蹤範圍內，而且在透過郵件附件把檔案來回傳遞的交付現場，共同編輯的歷程記錄原本就無法發揮作用。

結果就是，當顧客收到反映了審閱意見的修改版時，只能靠肉眼去找「哪裡變了」。每次都把數十個工作表的文件從頭讀一遍並不切實際，實際情況往往變成憑「大概已經改好了吧」的感覺蓋下驗收章。

這就是驗收流於形式。驗收本是「確認交付物是否符合已達成合意的內容並加以接受」的程序，一旦這個環節流於形式，日後一旦發現問題，就會演變成「不是已經驗收通過了嗎」「不對，交付的形式根本無法確認」這種毫無意義的爭論。

2.2 規格變更的合意記錄無法留存

開發過程中規格必然會變動。這時如果文件是 Excel 方格紙，變更的往來就容易變成「一堆檔案副本」。想必很多人都對 規格書_v2_最終_修正(2).xlsx 這樣的檔名不陌生。

問題在於，事後無法確定哪一個版本才是「雙方合意的版本」。當就追加費用或交期產生分歧時，作為依據的正是那份合意文件。如果連是哪一份文件都說不清楚，就會變成各說各話。

2.3 在維護階段與實作產生落差

方格紙文件的更新成本很高，因此在交付後的改修過程中會逐漸不再被更新。沒人敢碰，怕一動版面就亂掉；圖案中的文字又搜尋不到，容易漏改──這些問題不斷累積，數年後就會變成「規格書是有，但沒人知道它是否還符合現況」的狀態。

為這種狀態買單的，是下一次改修的時候。如果文件靠不住，就只能從頭調查實物(正在運作的系統與原始碼)，這部分工時會被加到報價裡。文件得不到維護，最終會以未來改修費用上漲的形式反彈回來。

2.4 顧客手邊難以實際運用

以列印為前提編排的版面，在螢幕上很難閱讀。而且由於內容分散在大量工作表和圖案當中，全文檢索很難發揮作用，尋找「那項規格到底寫在哪裡」要花不少時間。顧客這邊想追加運用備註、或挪用作公司內部說明資料等二次利用也很困難，好不容易付費換來的文件，往往變成「只是被保管著」而已。

3. 合約的觀點 ── 規格書是一種「成果物」

在進入格式的討論之前，先說一層更上位的話題。規格書・設計文件，只有在合約中被明確定為交付物，才會成為與程式同等的、合約意義上的成果物。反過來說，未在合約中明確的文件，並不理所當然地屬於應當交付的範圍。IPA 的資訊系統・模型交易・合約也是採用在個別合約中明確交付物、並約定驗收方法與期間的結構。關於該模型合約的整體框架，在另一篇文章「委託開發・維運保養的合約該如何簽訂 ── 借鑑 IPA『模型交易・合約』學習準委任與承攬的區分運用」中有詳細說明。

也就是說，Excel 還是 Word 這類格式上的討論，只有在以下這些基礎都已確定之後，才真正有意義。

• 哪些文件屬於成果物：不是籠統的「文件一整套」，而是要具體列到文件名稱這一層級
• 要以什麼形式收到：是否包含可編輯的原本(Word 或 Excel 檔案)。只有 PDF 會在維護時造成困擾
• 驗收的方法：確認哪些內容才算接受。修改版的差異該如何呈現
• 著作權・二次利用的處理：顧客能否在公司內部複製、修改。將來把維護委託給別的公司時，能否把文件轉交出去

如果合約裡沒有確定這些，那麼無論選擇多麼完善的格式，都會在「這份文件到底算不算交付對象」這個問題上產生糾紛。關於發包前應梳理的事項，也可以參考「委外・委託開發 Windows 應用程式前該整理的事項」。

4. 交付格式的選項 ── 以「能否成立為交付物」來比較

基礎確定之後，就可以選擇格式了。評價軸如同開頭所述，共有 4 項：顧客的可讀性 / 審閱・驗收的容易度 / 規格變更的差異管理 / 維護階段的持續性。

評價符號的意義如下所示。判定的基準是「該格式本身作為工具是否具備該機制」，並不包含能否透過運用巧思來補足。

標上 △ 的 3 處，先把理由寫在前面。

• Excel 的差異管理標為 △：因為它沒有相當於 Word 追蹤修訂那種能用紅字顯示差異的機制。雖然有儲存格值的版本歷程記錄與 Spreadsheet Compare，但這些多半以共同編輯環境為前提，或是圖案・文字方塊中的文字不在範圍內(第 2.1 節)。結果還是得靠「另外附上變更部分一覽」這種運用規則來補足。
• PDF 在維護上的持續性標為 △：閱讀本身沒有問題，但無法保持結構繼續更新下去，因此需要另外準備可編輯的原本(第 4.3 節)。
• Wiki 在維護上的持續性標為 △：更新的容易度反而是最高的，但合約結束之後文件是否留得下來，取決於工具的合約與設定。如果沒有一開始就確定匯出的可行性、工作空間的所有權、帳號的處理方式，就會在合約結束的同時失去文件的存取權(第 4.5 節)。

以下分別補充說明。

4.1 Word ── 以文章為主的規格書的第一候選

像概要設計文件、業務流程說明這類「用文章來敘述」的文件，本來就應該用文書處理軟體來寫。Word 從一開始就配齊了交付文件所需的各種工具。

• 標題樣式與自動目錄：文件結構變得清晰，可以從目錄直接跳到目標位置
• 追蹤修訂(校閱功能)：修改版哪裡變了，會以紅字顯示出來。審閱與驗收的實際效果完全不在同一個等級
• 註解功能：顧客提出的意見及其回覆會保留在文件上
• 文件比較：事後也能顯示兩個版本之間的差異

顧客那邊不需要特殊工具，也不需要額外學習，直接作為交付格式就能通過，這在實務上也是一大優點。

需要注意的是，如果不使用樣式，只做出「外觀看起來整齊」的文件，就會掉進同一個坑裡，可以稱之為 Word 方格紙。標題要用標題樣式，版面配置要用格式設定，而不是連續按空白鍵。另外，「到底哪個是最新版」的問題在 Word 上同樣會發生，因此需要與後文提到的版本管理運用方式搭配使用。

4.2 讓 Excel 回歸「真正的表格」

畫面項目定義書、代碼一覽表、權限矩陣這類文件，本質上就是表格。用 Word 來寫反而不方便，Excel 才是正解。不過要用的不是方格紙，而是能當作資料處理的樸實表格。

• 一行對應一筆記錄，一列對應一個屬性。一個工作表只放一張表
• 不用合併儲存格來做版面配置。標題只占開頭一行
• 不為了列印時的美觀而破壞資料結構(列印用的排版另外想辦法處理)

這樣做出來的文件，在維護時就能以機械化的方式處理。像是把項目定義和實際的資料庫定義互相核對、把一覽表直接當作測試項目的基礎等重複利用方式都能派上用場，「確認文件是否與實作產生落差」這件事本身也會變得輕鬆。

4.3 PDF ── 用來凍結「已合意版本」的格式

PDF 無法輕易編輯，這既是缺點，也是優點。作為規格書的原本，PDF 是不合格的，但作為通過驗收的版本、規格變更中合意版本的快照，它卻很適合。由於不會被不小心改寫，因此可以發揮「在這個時間點我們是這樣合意的」這種記錄的作用。

不過嚴格來說，PDF 也是可以重新製作的。它作為記錄的效力，並非來自 PDF 這種格式本身，而是來自雙方各自保管著同一份檔案這件事，因此請務必搭配相應的運用方式，例如透過郵件寄送並連同寄送記錄一起留存、由雙方各自在自己的環境中保管等。如果還需要在糾紛時具備證據力，加上電子簽章或時間戳記也是選項之一。

還有一項原則很單純：PDF 永遠要與可編輯的原本成套交付。只交付 PDF，會壓縮顧客未來的選項(公司內部自行運用、將維護委託給其他公司)。

4.4 以 Markdown + Git 作為原本，生成 Word / PDF 後交付

從開發公司管理的角度來看，近年來把規格書寫成 Markdown，並與原始碼放在同一個 Git 儲存庫中進行版本管理的做法逐漸普及。這樣可以取得逐行差異，能用和程式碼審查相同的機制來審閱文件，變更的來龍去脈也會作為歷程記錄留存下來(作為開發實務的記錄已經足夠，但若還要求能作為稽核或糾紛應對的證據，就需要另外配套禁止改寫歷程記錄等運用措施)。

這種做法不需要要求顧客使用 Git。只要把原本用 Markdown 管理，交付物則透過 Pandoc 等轉換工具生成 Word 或 PDF，顧客就仍然像以往一樣，只收到 Word/PDF 即可。這樣能夠同時兼顧開發方的管理效率與顧客方的可讀性。

這裡出現的Pandoc是一款用來相互轉換文件格式的免費工具(開源、以命令列執行)。可以從 Markdown 轉換為 Word(.docx)、PDF、HTML 等多種格式，只要把放入自家 Logo 與標題樣式的 Word 檔案指定為「範本」，生成出來的 Word 就能統一成公司內部標準的樣式。導入這套做法的只有開發公司這一方，發包方不需要新的工具。這一點容易被誤解，在提案時應該明確傳達。

把流程畫成圖，如下所示。

［開發公司端］
  用 Markdown 撰寫規格書
        ↓
  在與原始碼相同的 Git 儲存庫中管理
    ・可以看到逐行差異
    ・能用和程式碼審查相同的機制審閱文件
    ・何時・誰・為何變更會留在歷程記錄中
        ↓
  用 Pandoc 轉換(指定自家範本的 Word 檔案作為樣式)
        ↓
  生成 Word / PDF
        ↓
─────────── 交付 ───────────
        ↓
［發包方端］
  和以往一樣收到 Word / PDF 並閱讀・審閱
        ↓
  修改要求以「註解」回覆(不直接改寫生成物)
        ↓
  開發公司端反映到原本的 Markdown 中，重新生成後再次交付

需要注意的是，要在合約上明確「哪一方才是原本」。如果顧客直接在生成出來的 Word 檔案上修改，就會與原本產生分歧，因此如圖末所示，需要事先約定運用規則，例如修改要求以註解方式提出，再反映到原本那一側。

4.5 Wiki・線上工具 ── 持續維護時的「活規格書」

對於持續有維護合約、改修較為頻繁的系統而言，用 Notion 或 Confluence 這類線上工具持續更新規格書，也是一種有力的做法。這種形式檢索性高，變更歷程記錄會自動留存，比起「交付即結束」，更容易維持成一份「活文件」。

不過從交付物的角度來看，需要一開始就確定好合約結束時會留下什麼。匯出格式(能否匯出成 Word 或 PDF)、工作空間的所有權與費用負擔、瀏覽帳號的處理方式。如果把這些問題模糊處理，就會被特定工具鎖定，存在合約結束的同時失去文件存取權的風險。

5. 如何推進規格變更的往來溝通

即使把格式整理好，如果沒有配套的運用方式，「到底哪個是最新版」的問題依然會重演。因為規格並不是交付完就結束，無論在開發中還是維護階段，都會持續變動。以下是推薦的基本做法。

1. 準備一份變更管理台帳：用一覽表記錄變更編號・日期・內容・影響(費用/交期)・合意者，一行記錄一項。這份台帳本身用 Excel 的樸實表格就足夠了。讓它與 IPA 模型合約的變更管理程序(參見前述文章)相對應
2. 文件的修改要以能看到差異的形式往來：如果是 Word，就開啟追蹤修訂後傳送修改版，顧客主要核對紅字部分。如果擔心追蹤修訂有漏記，接收方可以用 Word 的「比較」功能，把它和上一次的合意版互相核對，這樣也能檢測出遺漏。達成合意後，套用修訂並確定該版本
3. 確定版本編號規則：把通過驗收的版本定為 v1.0，此後每達成一次變更合意就升到 v1.1、v1.2。檔名中不要使用「最終」「修正」「(2)」這類字樣
4. 把已合意的版本用 PDF 凍結，由雙方保管：讓任何人事後都能確定當初是就哪個版本達成合意的

不管用什麼工具，只要這 4 點能夠運作起來，「不知道哪裡變了」「不知道哪個是合意版」這兩大糾紛基本上都能避免。反過來說，比起工具的選定，運用規則的合意才是核心。

6. 發包方在簽約前應確認的事項

面向發包方，把在報價・簽約階段應確認的事項整理成一份檢查清單。

• 成果物清單中是否具體到文件名稱這一層級列出了規格書・設計文件(是否只是籠統寫著「文件一整套」)
• 是否能拿到可編輯的原本(Word/Excel 檔案等)。是不是只有 PDF
• 收到修改版時，是否以能看清哪裡變了的形式(追蹤修訂・變更部分一覽)來提供
• 維護合約的範圍中是否包含改修時的文件更新。如果不包含，能否接受文件會逐漸產生落差這個前提
• 文件的著作權・二次利用如何處理。將來把維護委託給別的公司時，能否把文件轉交出去
• 規格變更的程序(變更管理台帳・合意記錄的留存方式)是否已經確定

從受託方的角度來看，這份清單同樣可以直接用於整理報價。要寫哪份文件、寫到什麼詳細程度，本身就是工時，也就是金額。如果在成果物範圍模糊不清的情況下接單，臨近交付時就容易出現「原以為這份文件理所當然也包含在內」這樣的落差。事先就文件清單與格式達成合意，能同時保護雙方。

總結

關於委託開發中交付的規格書，把本文的要點彙整如下。

• 交付的規格書應從驗收、規格變更、維護的觀點來選擇格式，而不是只看「開發過程中是否好寫」
• Excel 方格紙的本質問題在於：因看不到差異而導致的驗收流於形式、合意記錄的喪失，以及因更新成本過高而導致的與實作產生落差
• 結論不是「全面廢除 Excel」，而是回歸適得其所：文章用 Word(樣式+追蹤修訂)，表格用 Excel 的樸實表格，合意的記錄用 PDF 凍結
• 用 Markdown+Git 管理開發方的原本，並生成 Word/PDF 作為交付物的做法，能夠同時兼顧雙方的優點
• 在格式之前，先在合約中決定成果物清單・可編輯原本的交付・著作權的處理方式。比起工具，運用規則的合意才是核心

另外，關於用程式讀寫 Excel 的話題(報表輸出)，收錄在「Excel 報表輸出該怎麼做 - COM 自動化 / Open XML / 範本方式的判斷表」中；合約的架構方式，則收錄在IPA 模型交易・合約解說文章中。歡迎一併閱讀。

參考連結

• IPA 資訊系統・模型交易・合約 ─ 第 3 章提到的、用來訂定交付物之明確約定・驗收方法與期間・變更管理程序的合約範本。發包方・受託方皆可免費取得
• IPA「資訊系統・模型交易・合約」第二版(因應民法修正的重新檢視) ─ 現行的第二版，以及其解說
• Pandoc ─ 第 4.4 節提到的文件轉換工具官方網站。包含支援格式一覽，以及指定 Word 範本等使用方式
• IPA 非功能需求等級 ─ 用於整理規格書中容易漏寫的非功能需求。解說請見另一篇文章

給正在考慮委託開發・維護的您

合同會社小村軟體在承接 Windows 業務應用程式的委託開發時，會依照本文介紹的思路，一開始就與發包方就成果物文件的範圍・格式・更新的運用方式達成合意。此外，對於既有軟體的改修，我們也承接從「雖然有規格書，但不知道是否符合現況」這種狀態開始的調查工作。包括規格書的整備與交付格式的重新檢視在內，歡迎隨時洽詢。

相關文章

共用相同標籤的最新文章。能以相近的主題延伸理解。

相關主題

與本文相近的主題頁面。以本文為起點，可進一步連到相關服務與其他文章。

與本主題相關的服務

本文連結到以下服務頁面，歡迎從最接近的入口查看。

常見問題

整理諮詢這個主題時常見的問題。

發包方指定了 Excel 方格紙的範本，只能照做嗎？

遵從對方指定的交付格式，本身確實是受託方應盡的本分，但值得先確認一下指定這樣做的目的。如果目的是滿足公司內部的文件標準或應對稽核，往往還有餘地提出用 Word 的樣式來滿足同樣的要求；而且範本只是從很久以前沿用至今的慣例，這種情況也不少見。即使無法變更指定的格式，也可以透過運用上的巧思──例如在修改版中附上「變更部分一覽」、把已合意的版本用 PDF 凍結──來緩解大部分因看不到差異而產生的問題。

規格書只交付了 PDF，這樣沒問題嗎？

在當下這個時間點因為還能閱讀，看起來不算問題，但到了維護・改造階段就會遇到困擾。用專用工具編輯 PDF 並非不可能，但要像 Word 或 Excel 的原本那樣保持結構繼續更新下去並不切實際，每次規格變更都會讓它與實作的落差進一步擴大。而且將來如果要把維護委託給別的公司，沒有可編輯的原本，文件也很難順利交接。穩妥的做法是在簽約時就把「交付內容包含可編輯格式(Word 或 Excel 的原本)」明確寫入成果物的條件中。若已經只拿到 PDF，不妨與開發公司商量，請對方提供原本。

規格書應該請對方寫到多詳細？

並不是「越詳細越好」。文件越詳細，更新成本就越高，在維護階段也越容易與實作產生落差。大致的標準是：行為的界定要達到能作為驗收基準使用的程度，並且保留維護・改造時會被參考的資訊(畫面項目、資料結構、外部串接、業務規則)。反過來說，只要讀程式碼就能明白的實作逐項說明，留在程式碼和註解裡比留在文件裡更不容易產生落差。要寫哪份文件、寫到什麼詳細程度，直接關係到工時，也就是報價金額，因此這是簽約前就應該協調好的事項。

交付後規格書的更新，是誰的責任？

這取決於合約。如果維護合約的範圍中包含「改修時更新設計文件」，那就是受託方的工作；如果不包含，就要每次改修時個別發包委託文件更新，或是接受文件會逐漸產生落差這個前提。最容易引發糾紛的，是雙方都沒有明確約定這一點，卻各自想當然地認為「文件理所當然會被更新」。建議在簽訂維護合約時，把哪些文件屬於維護對象，具體到文件名稱的層級明確寫下來。

作者檔案

本文作者的個人檔案頁面。

Go Komura

小村軟體有限公司 代表

以 Windows 軟體開發、技術諮詢與故障調查為中心，在難以重現的故障調查與既有資產仍在運作的專案上具有優勢。