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.
Qué hace
Genera hasta nueve documentos de incorporación para un nuevo compañero a partir del código real de cualquier proyecto y los escribe en la carpeta docs/.
Cómo funciona
- Lee el proyecto en tres pasadas (estructura, esqueleto y un flujo completo) y registra rutas, clases, glosario y dudas pendientes en
docs/.project-map.md. - Elige cuáles de los nueve capítulos escribir según el tipo de proyecto (sistema, backend web, frontend web, biblioteca o script de datos). Los capítulos omitidos conservan su número y se indica el motivo.
- Redacta cada capítulo desde una plantilla. Primero debe volver a leer cada fragmento de código del archivo real y citarlo como
path:line; marca como no verificados los comandos que no ha ejecutado. - Escribe
docs/README.md(qué capítulos leer según el objetivo), repasa una lista de comprobación e informa de lo omitido y de lo que sigue sin estar claro.
También puede escribir solo algunos capítulos o actualizar documentación existente comparándola con el commit registrado en el mapa del proyecto.
Para qué sirve
- Entregar una base de código a un nuevo compañero
- Entender un repositorio desconocido
- Actualizar documentación de arquitectura obsoleta
Las plantillas están en chino, por lo que los documentos se generan por defecto en chino aunque lo pidas en inglés.
Riesgo medio: crea y reescribe archivos Markdown en docs/, incluido el oculto docs/.project-map.md. Si docs/ ya contiene archivos, debe preguntar si quieres sobrescribirlos, omitir los existentes o copiarlos a docs.bak/. No contiene scripts, no accede a la red ni elimina nada. Se probó una vez con un proyecto de ejemplo de unas 90 líneas en un directorio temporal, solo con las herramientas Skill, Read, Glob y Write y sin shell: no se ejecutaron comandos y sus instrucciones de compilación y ejecución no están verificadas. No se probó la pregunta de sobrescritura porque docs/ no existía. Confirma los cambios de docs/ en Git o haz una copia antes de ejecutarla y revisa posibles rutas o nombres de clases incorrectos en los documentos.