Skip to content

CHIANI04/fju-im-spec-writer

fju-im-spec-writer

Verified

用於生成/修改輔仁大學資訊管理學系(FJU IM)《系統分析與設計》課程的專題規格書(SA文件),依照老師規範的章節結構、格式與審查標準產出Word文件。觸發時機:使用者提到「規格書」「SA文件」「專題文件」「systems analysis document」,或提到章節如「使用者故事」「User Story」「資料庫設計」「介面藍圖」並要求生成/修改/檢查專題文件內容時。也適用於兩人以上協作生成同一份文件、需要追蹤章節進度時。不適用於:一般文件寫作、與此課程規範無關的規格書、程式碼撰寫本身。

FJU IM Spec Writer(輔大資管 專題規格書生成 Skill)

這個skill做什麼

依照輔仁大學資管系《系統分析與設計》課程老師的規範、章節結構與歷屆優秀範例格式,生成或修改畢業專題的規格書(Word文件)。核心目標:每次產出都符合老師的格式與審查標準,而不是每次現場自由發揮出不一致的內容。

設計思路參考自 obra/superpowers(https://github.com/obra/superpowers)的兩個核心原則:①動手寫之前先透過提問把資訊釐清(brainstorming思路,見階段二),②以小單位反覆「生成→驗證」而非全部寫完才後驗(TDD式紅燈綠燈循環,見階段三)。**注意:這裡借的是「先問清楚再寫」「小單位反覆驗證」這兩個工作節奏,不是輸出檔案的切分方式——不論分成多少小節逐一核對,最終仍然只交付一份完整的docx。**

也參考 mattpocock/skills(https://github.com/mattpocock/skills)的`grill-with-docs`思路:與其每次生成章節都臨時問一輪問題,不如**第一次做一場完整的深度訪談,把整個專題背景一次問透,存成 state/project_context.md**,之後生成任何章節都先讀這份檔案取用背景資訊,不用重複發問。見「階段○:專案深度訪談(只需做一次)」。

階段○:專案深度訪談(只需做一次,新專案開始時執行)

在開始生成任何章節之前,若 state/project_context.md 不存在或內容空白,先執行一場完整的深度訪談,把整個專題的背景一次問清楚,存成這份檔案,之後所有章節生成都直接讀取,不需要每次重問。

這份檔案跟 state/project_state.md 的差別:

  • project_context.md:專題的內容本身(背景、利害關係人、競品、功能模組、資料需求等),問過一次就長期沿用,是「知識庫」
  • project_state.md:各章節的進度狀態(誰在寫、寫到哪、待確認事項),隨時間變動,是「進度表」

訪談應涵蓋的範圍(對照 chapter_requirements.md 各章節需求整理成一次性問題清單):

  • 專題名稱、核心概念、要解決的問題是什麼、對誰造成困擾
  • 利害關係人有哪些人、各自的期望
  • 需求蒐集方法(訪談過誰、發過問卷嗎、觀察過現場嗎)
  • 主要競品/替代方案有哪些,各自優缺點
  • 目標客群與價值主張
  • 系統的功能模組概況(如智慧倉儲導航系統的E1-E9)
  • 預計使用的技術/資料庫/工具
  • 使用規則版本(111-113版或114版,或混用)
  • 團隊成員與分工

訪談後:把回答整理成結構化的 project_context.md,讓使用者確認內容無誤。之後任何時候要生成章節,先讀這份檔案,只在該章節需要的細節超出這份檔案範圍時(例如某個User Story的具體輸入資料),才另外追問,不用把整個背景重問一次。

兩人協作時:只要兩人共用同一份 project_context.md(放在skill包之外的共用雲端資料夾或Git repo——skill包本身是個人帳號各自的靜態副本,不會互相同步,見SKILL.md「兩人協作注意事項」),任一人生成任何章節時都能立即取用對方訪談時提供的背景,不用重新向對方問一次已經回答過的問題。

若專題背景後續有變動(如competitor分析有新發現、範圍調整、方向轉彎):

  • 可以直接修改或推翻 project_context.md 裡的任何內容,這份檔案本來就是活的,不是寫死不能改的紀錄
  • 修改時,直接更新對應段落即可,不需要重新跑一次完整訪談
  • 建議在 project_context.md 底部維護一個簡短的「修訂紀錄」(日期+變動內容一行摘要),方便回溯什麼時候改了方向、為什麼改
  • 重要:修改背景知識庫後,務必檢查是否有已經生成過的章節,是根據舊的背景內容寫的——去看 state/project_state.md 裡哪些章節狀態是「草稿中」或「定稿」,對這些章節重新跑一次 review_checklist.md 的一致性檢查,確認內容有沒有跟新的背景方向矛盾(例如競品分析換了,但系統範圍還是根據舊競品寫的)。若有矛盾,该章節狀態應改回「待確認」,提醒使用者需要重新檢視

使用前必讀

  1. 確認規則版本(有預設值,不用每次重問):老師規範在114學年度做過改版(第一章、第四章結構不同)。state/project_context.md裡的「使用規則版本」欄位已內建一組預設建議(第一章用114版、第四章視系統開發進度動態選114版或111-113版過渡版、附錄額外加程式分工與實際工時表)。除非使用者明確表示要用其他版本,否則直接套用這個預設,不需要每次生成前都重新詢問——只在以下情況才需要跟使用者確認:①project_context.md裡這個欄位完全空白(從未設定過)②使用者明確提出想用不同版本③要開始寫第四章時,需要確認系統目前是否已完成、有無實測資料,才能判斷用114版或111-113過渡版
  2. 先讀 reference/ 底下所有檔案,不要憑記憶生成內容:
    • chapter_requirements.md:各章節該寫什麼、常見扣分點、111-114版可能混用的注意事項
    • style_guide.md:各種表格與故事卡的精確格式(逐字模板)
    • database_design_rules.md:資料庫設計的正規化、命名規範
    • format_pattern_guide.md:每個段落該用文字段落、表格、還是條列——老師不喜歡為了用表格而用表格,務必依此表對照,不要自行決定格式
    • document_formatting.md:文件層級的格式設定(字型、字級、頁碼、目錄欄位、頁面邊界等),直接從114範本.docx的XML解析取得的實際數值,生成docx時務必套用,不要憑印象隨意設定
    • content_synthesis_guide.md:逐段落的來源優先策略與老師隱性偏好分析——111/114/音樂祭三份文件在各章節的完整度、寫作深度不一,這份文件明確指示每個小節該優先參考哪份來源、該截取哪些優點、該避開哪些重疊內容,生成第一至四章、附錄的任何內容前都必須先讀這份文件對應段落,不要憑印象決定要參考哪份來源
    • review_checklist.md:生成後的品質自我檢查清單
  3. 產出文件時使用 docx skill(/mnt/skills/public/docx/SKILL.md),依照 templates/ 底下對應版本的官方範本作為排版參考。
  4. 若 examples/ 底下有歷屆優秀範例(如Beaton_音樂祭平台_參考範例.pdf),生成內容時可對照這份真實案例的實際寫法(尤其User Story的Given/When/Then怎麼寫得細緻、資料庫關連結構的實際呈現、SWOT段落的敘述風格),但這份範例的完成度不代表可以照抄內容——它只是格式與寫作手法的參考,實質內容仍須來自使用者提供的真實資訊。注意:這個檔案是透過指導教授取得的他人畢業成果,不屬於公開GitHub repo的一部分(見.gitignore),若skill包是從GitHub下載的,這個檔案可能不存在,不影響skill其他功能運作。

運作流程

階段一:確認情境

  • 先檢查 state/project_context.md 是否存在且有內容——若不存在,先執行「階段○:專案深度訪談」再繼續

  • 檢查 project_context.md 裡的「參考文件設定」欄位是否已確定——若這個欄位是空的或從未問過,在開始生成任何章節內容前,必須先問使用者一次:

    「這個skill目前內建的預設參考來源是111範本、114範本、Beaton音樂祭平台範例(見reference/content_synthesis_guide.md),逐章節的優先順序摘要是:第一章結構採114版骨架、內容截長補短參考111與Beaton;第二章格式參考114、內容參考111與Beaton;第三章資料庫設計參考114、介面與資源需求參考Beaton;第四章採六節混合結構;附錄採Beaton完整結構。要直接套用這組預設嗎?還是你手上有不同的參考範例文件(例如你們老師換了新範本、或有其他學長姐的範例),想改用不同的參考來源?」

    • 若使用者選擇套用預設,在project_context.md的「參考文件設定」欄位記錄「採用內建預設(111/114/Beaton)」,之後同一專題不用再問
    • 若使用者選擇指定其他來源,詢問使用者要上傳/提供哪些新的參考文件,讀取後依content_synthesis_guide.md同樣的分析方法(逐章節比對完整度、萃取寫作優點與隱性偏好)重新產出一份對應的分析,可另存為content_synthesis_guide.local.md或直接請使用者確認要覆蓋原檔案,並在project_context.md記錄「採用自訂來源:{文件名稱}」
    • 這一步只在專題第一次生成內容時問,不是每個章節都問;之後除非使用者主動提出「這章我想換參考來源」,否則沿用已記錄的設定
  • 讀取 state/project_state.md,了解目前進度(哪些章節已完成、誰做的、有無待確認事項)

  • 若是全新專案,先協助使用者填寫「專題基本資訊」(專題名稱、規則版本)

  • 若使用者要生成/修改特定章節,先確認該章節是否已有人在處理,避免衝突

階段二:蒐集資訊(針對該章節的細節缺口,不是重問整個背景)

  • 先讀 state/project_context.md,能從裡面取得的背景資訊不用重問
  • 對照 reference/chapter_requirements.md 中該章節的規則,列出這一章節需要哪些「超出project_context.md範圍」的具體細節(例如某個User Story的輸入欄位、某段落的量化數據),一次性條列給使用者確認/回答,而不是寫到哪缺到哪才臨時問一句
  • 不要自己腦補專案細節(如問題陳述的具體數據、訪談人數等)
  • 資訊確實問過但使用者當下無法提供時(例如還沒做市場測試),才標記「⚠️待確認」寫入內容中,並同步記錄到 state/project_state.md 的「待確認事項清單」——這跟「沒問就自己編」是兩回事

階段三:逐節生成、逐節核對(參考superpowers的TDD思路:小單位驗證,不累積錯誤)

重要:這只是生成過程中的內部工作節奏,不代表輸出多個檔案。最終仍然只交付一份完整的docx。

  • 依 style_guide.md 的模板格式,以「小節」為單位依序撰寫(例如第一章拆成:問題陳述→利害關係人分析→需求蒐集方法→競爭者分析→市場定位,一節一節寫)
  • 每寫完一小節,立刻對照 review_checklist.md 中對應該小節的檢查項,確認通過才進入下一小節;沒通過就先在這一小節修正,不要帶著問題往下寫,避免錯誤累積到最後才發現要整段重寫
  • 先對照 format_pattern_guide.md 確認這一小節該用文字段落、表格、還是條列,不要自行判斷。原則上:敘述性、需要邏輯連貫的內容(問題陳述、SWOT、心得等)一律寫成完整段落,不要條列化;結構化、多筆同類資料(角色說明、User Story、資料庫、介面、經費)一律用表格
  • 對話中會逐節呈現內容給使用者看(「這節先給你看,核對後再繼續下一節」),方便使用者中途發現問題就喊停修正,而不是等一大段寫完才發現方向錯了
  • 每個小節生成時都要對照已完成的其他章節內容做一致性檢查(對照 chapter_requirements.md 最後一節「全文件層級的一致性檢查重點」),例如:
    • 問題陳述提到的問題,系統發展目的要有對應解方
    • 系統範圍的功能,第二章要有對應User Story
    • Epic/User Story優先順序要與資源需求、市場測試呼應
  • User Story撰寫務必遵守 Given/When/Then 規則(見 chapter_requirements.md),不要把畫面操作細節寫進接受條件
  • 開始寫第二章Epic/User Story優先順序(對應Sprint)前,必須先詢問使用者要分幾個Sprint,不能自行假設數量。詢問後依「先MVP、後加分功能」原則分配:核心必要功能放進早期Sprint,加分/進階功能放進後期Sprint
  • 資料庫設計章節同時套用學術正規化規範與範本表格格式
  • ⚠️ 開始寫資料庫設計(第三章一、資料庫設計)前,必須先確認專題實際使用的資料庫種類,不能預設任何一種。 步驟:①先讀project_context.md「技術規劃」欄位是否已記錄資料庫選型;②若空白或未問過,必須先問使用者「這個專題實際使用哪一種資料庫?(PostgreSQL/MySQL/SQLite/Firestore/其他)」,得到明確答案並記錄進project_context.md後才能動手寫型態欄位;③若已有記錄,生成時要主動核對每個型態欄位是否符合該資料庫的真實語法(依reference/database_design_rules.md的資料庫語法對照表),不能照抄參考檔案裡的範例字面語法——不同資料庫的型態語法不能混用(例如PostgreSQL沒有BIGINT(11)這種顯示寬度語法、沒有TINYINT、用SERIAL/IDENTITY取代AUTO_INCREMENT);④若中途發現已生成內容用錯資料庫語法,主動告知使用者並提出修正,不要等使用者自己發現
  • 文字內容一律使用全形標點符號(如「,」「。」「:」「;」「()」),不要用半形逗號、句號、冒號、分號、括號——這是文件全文的統一規則,不分章節
  • 章節結構(尤其第一章、第四章)、附錄要不要含程式分工/實際工時表,優先套用project_context.md裡記錄的預設值,不需要每次重問;第四章已由使用者明確選定六節混合結構(見content_synthesis_guide.md),不需要再詢問版本;若使用者主動要求改變版本組合,優先照使用者指示,並詢問是否要更新project_context.md裡的預設值

資訊不足或生成內容存疑時如何處理(重要)

  • 這個skill不會、也不應該替使用者捏造專題實質內容(如訪談人數、問卷結果、系統邏輯細節、資料庫欄位設計)
  • 遇到生成某段落需要的具體資訊使用者還沒提供時,主動提問並等待回覆,不要用「假設」或「範例」帶過——例如生成「需求蒐集方法」時,若使用者沒說訪談了幾人、發了幾份問卷,要直接問,而不是編一個「訪談5位使用者」交差
  • 若使用者當下無法立即回答,才標記「⚠️待確認」寫入文件,並記錄到 state/project_state.md 待確認事項清單,之後由使用者或組員補上
  • 生成過程本質上仍是LLM,可能出現幻覺——尤其容易發生在:編造看起來合理但使用者沒提過的數據、把使用者提供的A功能細節誤植到B功能、過度延伸使用者沒說清楚的需求。逐節核對時應主動比對來源(使用者這一小節實際提供了什麼),發現可疑內容要標記出來讓使用者核對,而不是預設它是對的

階段四:整份彙整與品質檢查

  • 所有需要的小節都逐節核對通過後,才把各小節彙整成完整章節、完整章節再彙整成完整文件(仍是同一份docx,不分檔)
  • 彙整時再跑一次 reference/review_checklist.md 的「全文件一致性」項目(逐節核對時檢查的是單節內部品質,這裡檢查的是跨章節的整體一致性)
  • 發現不一致或矛盾之處,明確告知使用者,不要默默修改使用者原意
  • 更新 state/project_state.md:章節狀態改為「草稿中」或「待確認」,記錄編輯者與時間

階段五:輸出

  • 用 docx skill 產出正式 Word 文件,套用範本(templates/)的整體排版風格(封面、目錄、修改紀錄表)
  • 呼叫 present_files 交付檔案

迭代修改

  • 老師給回饋後,只需針對該章節重新生成,不用整份重寫
  • 回饋內容記入 state/project_state.md 的「老師回饋紀錄」,避免下次改到同樣的問題
  • 每次交付版本可在文件的「修改紀錄」表格中遞增版本號並註記變更內容

兩人協作注意事項

重要限制,務必先了解:Claude.ai的custom skill是上傳到個人帳號的,state/底下的檔案只是skill包裡的靜態範本骨架。在對話中對這些檔案做的更新,不會自動同步回你上傳的skill包,也不會同步到組員的skill包。真正要達成「共用」,你們需要一個skill之外的外部共用空間存放「有實際內容」的project_context.md與project_state.md,例如:

  • Google Drive共用資料夾(若有連接Google Drive,可直接讀寫該檔案)

  • 你們專題本來就有的GitHub repo

  • 或最簡單:誰更新了內容,就把最新版檔案傳給我,下次對話開頭先貼給我

  • 兩人各自使用時,只要共用同一份外部存放的project_context.md/project_state.md(而不是各自skill包裡的空白範本),就能看到對方最新進度與背景資訊

  • 生成某章節前,務必先讀最新版的 project_state.md 確認該章節目前狀態,避免兩人同時生成同一章節造成衝突

  • 若發現兩人各自生成的章節格式風格不一致,在「整合檢查」階段統一格式(對照 style_guide.md 而非互相配合對方風格)

一人使用時

state/project_state.md 依然有用,可當作個人的章節進度追蹤與待辦清單,流程完全相同,不需要任何額外步驟。

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall