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/，生成后请核对文档里的路径和类名是否正确。