I wrote the four files you asked for, all under docs/. I didn't run anything, so every command and example is untested.
| File | Lines (about) | Content |
|---|---|---|
01_architecture.md |
170 | Three layers, an annotated directory tree, the modules, and a "where is X" table |
04_code_walkthrough.md |
220 | Walk-through of creating a short link and following one, with sequence diagrams |
README.md |
35 | Which chapters to read for which goal, plus the skipped chapters |
.project-map.md |
90 | My reading notes, glossary and open questions |
- Skipped: chapters 02, 03 and 05–09 are listed in the index with the reason: you asked for a shorter run. The numbers are kept, so they can be added later. Chapters 05 and 06 note that the project has little to say there (no concurrency code, no build step).
- Length: 01 and 04 are well under the skill's 300-line target. The whole project is about 90 lines of Python, so I didn't pad them.
- Not verified:
- The README's run commands:
pip install,python -m shortlink.appandpytest. - The
curlexample. - My reading that sqlite3's
withblock doesn't close the connection. This is marked in the text.
- The README's run commands:
- Not covered in the docs:
- Behaviour under concurrent requests.
shortlink/__init__.py, which is empty.- The project isn't a git repo, so the docs have no commit to point at.
While reading the code I noticed two things:
create_linkdoesn't catch theRuntimeErrorthatshortenraises after five failed attempts at a unique code, so that case returns a 500.link_statscallsstoragedirectly and skips the service layer.
Both are in the docs as observations, not fixes.
Real run in a throwaway directory with a ~90-line Flask sample project (shortlink). Tools were limited to Skill, Read, Glob and Write, with no shell, so no command was executed. To keep the run short the prompt asked for only chapters 01 and 04 plus the project map and index. The skill wrote four files (about 505 lines in total); only the model's final message is shown, verbatim. The generated docs came out in Chinese because the skill's templates are Chinese.
它做什麼
依據任何專案的真實程式碼，為新同事產生最多 9 篇上手文件，寫入專案的 docs/ 目錄。
運作方式
- 分三步讀專案（輪廓、骨架、跟著一條完整流程走），把路徑、類別名稱、術語表和尚未弄清的地方記到
docs/.project-map.md。 - 依專案類型（系統、Web 後端、Web 前端、函式庫、資料腳本）決定寫哪幾篇；跳過的篇目保留編號並註明原因。
- 依範本逐篇撰寫。貼程式碼前必須重新讀該檔案，並標註
path:line；沒實際執行過的指令標為未驗證。 - 撰寫
docs/README.md（不同目的該讀哪幾篇），依清單自我檢查，最後回報跳過了什麼、還有什麼沒弄清。
也支援只寫其中幾篇，或對照專案記錄中的提交更新既有文件。
適合情境
- 把程式碼庫交接給新同事
- 快速理解陌生的儲存庫
- 更新過期的架構文件
Skill 範本是中文的，預設產生中文文件。
中風險：會在專案的 docs/ 目錄下新增並重寫 Markdown 檔案，包括隱藏檔 docs/.project-map.md。docs/ 已有內容時，Skill 要求先詢問你要覆蓋、跳過既有檔案，還是備份到 docs.bak/。沒有腳本、不連網、不刪除檔案。僅在暫存目錄中以約 90 行的範例專案試用過一次，工具只開了 Skill、Read、Glob 和 Write，沒有 shell，因此沒有執行任何指令，其建置與執行說明未經驗證；因為當時 docs/ 不存在，覆蓋前的詢問環節也沒有觸發。執行前請先提交或備份 docs/，產生後請核對文件中的路徑與類別名稱是否正確。