以「修仙築基」隱喻工程成長路徑的開源模板。
你不是在堆代碼，你是在煉一顆可長期演化的工程金丹。
- 目錄分區清楚：結構先於功能
- 步驟編號嚴格：流程可重現、可審核
- 前置條件單獨列項：不把風險藏在正文
- 失敗案例分開說明：錯誤要可學、可避、可追溯
- 文檔與代碼同構：代碼改一寸，文檔同步一寸
一句話：先築基，再結丹；先正道，再提速。
- 煉氣：能跑通最小示例（MVP）
- 築基：有清晰目錄、可讀文檔、可復現流程
- 金丹：有測試、CI、代碼審查規範
- 元嬰：有穩定接口、版本策略、回滾方案
- 化神：可模塊化演進、可跨團隊協作
- 合道：工程與產品節奏統一，長期維護成本可控
詩像：
代碼如劍，文檔如鞘；
無鞘之劍，鋒芒傷己。
築基若穩，萬法可生。
在開始之前，請逐項確認：
- 已安裝
git，且可正常 clone/pull/push - 已具備對倉庫的寫入權限（或已 fork）
- 已約定主要語言與運行環境版本（如 Node/Python）
- 已確認首個可驗證目標（例如：5 分鐘內跑通 demo）
- 已同意「小步提交、嚴格審查、文檔同步」協作規則
git clone <your-repo-url>
cd OpenSource-Foundation-Pill- 修改項目名與一句話定位
- 補充運行方式與環境要求
- 明確第一個可驗證輸入/輸出案例
- 建立清晰目錄分區（
docs/、src/、tests/、examples/） - 定義提交與 PR 規範（描述 why > what）
- 確保每次改動都有對應文檔更新
- 新人可在 5 分鐘內跑通最小案例
- Issue -> Commit -> PR -> Review 流程完整走通
- 核心文檔可支撐陌生成員理解與接手
.
├── README.md # 項目入口、境界路線、協作規約
├── docs/ # 架構決策、設計說明、路線圖
├── src/ # 核心實現（單一職責、低耦合）
├── examples/ # 最小可驗證示例（可直接運行）
├── tests/ # 單元/整合測試（行為保證）
└── .github/ # CI、Issue/PR 模板、社區規範
- 表象：前期開發很快，後期改一處炸三處
- 本質：缺少目錄邊界與責任分層，耦合失控
- 修復：先做模塊切分，再補測試與文檔
- 表象：核心作者離線後，團隊維護停滯
- 本質：知識只在腦中，未形成共享語義
- 修復：以 README + docs 為主線重建認知地圖
- 表象：PR 可以合，但質量不可預期
- 本質：缺少嚴格步驟和驗收標準
- 修復：強制編號流程與合併檢查清單
- 變更是否可復現、可驗證？
- 是否消除了可避免的特殊分支？
- 文檔是否與代碼同步更新？
- 是否附上失敗場景與邊界說明？
- 是否讓下一位工程師能快速接手？
- 增加標準開源模板（Issue / PR / Code of Conduct）
- 增加多語言最小樣例（Node.js / Python）
- 增加 CI 工作流（lint / test / release）
- 增加 ADR（架構決策記錄）範例
- 增加 Agent 協作文檔模板
本倉庫提供的是工程築基框架與協作方法論，不承諾：
- 自動適配所有技術棧與業務場景
- 在缺少維護投入下仍保持長期高質量
- 替代架構判斷、代碼審查與產品決策
請根據你的團隊規模、業務風險與合規要求進行調整。
模板是丹方，不是仙丹；修行仍需親自落地。
建議使用 MIT（可按需求調整）。
獻給所有把工程當作長跑、把維護當作品質的開源建設者。
願你我皆能：築基穩、金丹成、道心明。