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/ フォルダに書き込みます。
進め方
- プロジェクトを 3 段階（全体像、骨格、1 本の通しフロー）で読み、パス・クラス名・用語集・未解明点を
docs/.project-map.mdに記録します。 - プロジェクトの種類（システム、Web バックエンド、Web フロントエンド、ライブラリ、データスクリプト）に応じて書く章を決めます。省略した章は番号を残し、理由を明記します。
- テンプレートに沿って章ごとに執筆します。コードを載せる前に必ず実ファイルを読み直し、
path:lineで出典を示します。実行していないコマンドは未検証と明記します。 docs/README.md（目的別に読む章）を書き、チェックリストで自己点検し、省略した章と未解明点を報告します。
一部の章だけ書く、プロジェクトマップに記録したコミットとの差分で既存資料を更新する、といった使い方もできます。
向いている場面
- コードベースを新メンバーに引き継ぐとき
- 見慣れないリポジトリを素早く理解したいとき
- 古くなったアーキテクチャ資料を更新したいとき
Skill のテンプレートは中国語のため、英語で依頼しても生成される資料は中国語になります。
中リスク：プロジェクトの docs/ 配下に Markdown ファイルを新規作成・書き換えます（隠しファイル docs/.project-map.md を含む）。docs/ に既存の内容がある場合、上書き・既存ファイルのスキップ・docs.bak/ へのバックアップのどれにするか先に確認するよう指示されています。スクリプトなし、通信なし、ファイル削除なし。使い捨てディレクトリで約 90 行のサンプルプロジェクトに対し 1 回だけ試用しました。ツールは Skill、Read、Glob、Write のみでシェルはなく、コマンドは一切実行していないため、ビルド・実行手順は未検証です。docs/ が存在しなかったため、上書き前の確認は動作していません。実行前に docs/ をコミットまたはバックアップし、生成後はパスやクラス名が正しいか確認してください。