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에 기록합니다. - 프로젝트 유형(시스템, 웹 백엔드, 웹 프런트엔드, 라이브러리, 데이터 스크립트)에 따라 작성할 편을 정합니다. 건너뛴 편은 번호를 비워 두고 이유를 적습니다.
- 템플릿에 따라 편마다 작성합니다. 코드를 붙이기 전에 반드시 실제 파일을 다시 읽고
path:line으로 출처를 표시하며, 실행해 보지 않은 명령은 미검증으로 표시합니다. docs/README.md(목적별로 읽을 편)를 작성하고 체크리스트로 자체 점검한 뒤, 건너뛴 편과 남은 불확실한 부분을 보고합니다.
일부 편만 작성하거나, 프로젝트 맵에 기록된 커밋과 비교해 기존 문서를 갱신하는 것도 가능합니다.
이런 경우에 적합
- 코드베이스를 신규 팀원에게 인수인계할 때
- 낯선 저장소를 빠르게 이해하고 싶을 때
- 오래된 아키텍처 문서를 갱신할 때
Skill 템플릿이 중국어라서 영어로 요청해도 생성되는 문서는 기본적으로 중국어입니다.
중간 위험: 프로젝트의 docs/ 아래에 Markdown 파일을 새로 만들고 다시 씁니다(숨김 파일 docs/.project-map.md 포함). docs/에 이미 내용이 있으면 덮어쓰기, 기존 파일 건너뛰기, docs.bak/으로 백업 중 무엇을 할지 먼저 묻도록 지시되어 있습니다. 스크립트 없음, 네트워크 호출 없음, 파일 삭제 없음. 임시 디렉터리에서 약 90줄짜리 샘플 프로젝트로 한 번만 시험했습니다. 도구는 Skill, Read, Glob, Write만 열었고 셸이 없어 명령은 하나도 실행되지 않았으므로 빌드·실행 안내는 검증되지 않았습니다. 당시 docs/가 없어서 덮어쓰기 전 확인 단계는 동작하지 않았습니다. 실행 전에 docs/를 커밋하거나 백업하고, 생성된 문서의 경로와 클래스 이름이 맞는지 확인하세요.