Przejdź do treści
Biblioteka skilli
Programowanie · Pisanie

project-docs

/project-docs

Generuje dla nowych osób w zespole 9 artykułów dokumentacji w katalogu docs/: architekturę, założenia projektowe, przewodnik po kodzie, model uruchomieniowy, build, integrację i debugowanie.

Repozytorium
best-skills ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
13.09.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
6
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 13.09.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Generuje dla nowych osób w zespole 9 artykułów dokumentacji w katalogu docs/: architekturę, założenia projektowe, przewodnik po kodzie, model uruchomieniowy, build, integrację i debugowanie.

Wyzwalacze z opisu

生成项目文档新人文档上手文档架构文档代码导读项目理解深入理解项目onboarding 文档
Oryginalny opis (EN)

对任意代码项目生成一套面向新人的循序渐进文档集,输出到 docs/ 目录。含架构、设计思想、语言特性、代码导读、运行时模型、构建、对接、调试、设计规范共 9 篇,支持全部生成 / 只写几篇 / 更新已有文档。当用户提到"生成项目文档"、"新人文档"、"上手文档"、"架构文档"、"代码导读"、"项目理解"、"深入理解项目"、"onboarding 文档"、"给新同事看的文档"时使用。要按用户给的格式写论文章节、项目梳理、重点问题、简历项目描述的,用 codegen-doc。

Jak działa

  1. Step 0:判断要做哪种
  2. Phase 1:先读项目,把结果记下来
  3. Phase 2:按项目类型决定写哪几篇
  4. Phase 3:写
  5. Phase 4:写目录页,然后自查
Sekcje z nagłówków SKILL.md, w oryginale · 110 linii, 233 słów
Podgląd SKILL.md
---
name: project-docs
description: 对任意代码项目生成一套面向新人的循序渐进文档集,输出到 docs/ 目录。含架构、设计思想、语言特性、代码导读、运行时模型、构建、对接、调试、设计规范共 9 篇,支持全部生成 / 只写几篇 / 更新已有文档。当用户提到"生成项目文档"、"新人文档"、"上手文档"、"架构文档"、"代码导读"、"项目理解"、"深入理解项目"、"onboarding 文档"、"给新同事看的文档"时使用。要按用户给的格式写论文章节、项目梳理、重点问题、简历项目描述的,用 codegen-doc。
---

# project-docs:项目深度文档生成

输出到项目的 `docs/` 目录。核心约束:文档里的代码、类名、路径都必须来自真实文件,见 Phase 3。

## Step 0:判断要做哪种

| 用户表述 | 做什么 |
|---|---|
| 生成项目文档 / 新人文档 / 深入理解项目(没指定篇目) | 全部生成,Phase 1 → 2 → 3 → 4 |
| 帮我写架构文档 / 只要代码导读 / 写构建和调试 | 只写指定的几篇,读项目的范围可相应缩小 |
| 代码改了,更新文档 / 文档过期了 | 读 `docs/.project-map.md`,比对现在的代码,只重写受影响的篇目 |

**`docs/` 已经有内容时**:先列出已有文件,问用户是覆盖、跳过已存在的、还是备份到 `docs.bak/`。不要直接盖掉。

**不该用这个 skill 的情况**:用户要的是论文章节、项目梳理、重点问题清单、简历项目描述——也就是给导师、评委、HR、领导看,且格式由对方指定的东西,用 **codegen-doc**。这个 skill 只管给新同事看、要能照着上手的文档。

---

## Phase 1:先读项目,把结果记下来

记到 `docs/.project-map.md`。后面每一篇要用的路径、类名、代码,都从这个文件取。

分三步读,**不要试图把所有源文件都读完**:

1. **看轮廓** —— 目录树、构建和依赖文件、README,判断用什么语言、属于哪类项目
2. **看骨架** —— 入口文件读全文、接口和类型定义、列出每个模块干什么
3. **跟一个完整例子走一遍** —— 挑一个有代表性的示例或功能,从入口追到结束

怎么读、记成什么格式、什么时候可以停,见 [reference/explore.md](reference/explore.md)。把那份模板填完再进 Phase 2,其中术语表至少 5 条。

---

## Phase 2:按项目类型决定写哪几篇

```
01_architecture.md        → 架构:项目长什么样
02_philosophy.md          → 思想:为什么这样设计
03_lang_concepts.md       → 语言特性:读代码前的准备
04_code_walkthrough.md    → 代码导读:跟着真实流程走一遍
05_runtime_model.md       → 运行时:并发和生命周期
06_build_guide.md         → 构建:怎么编译运行
07_integration_guide.md   → 对接:怎么写新功能
08_debug_guide.md         → 调试:出问题怎么查
09_design_conventions.md  → 规范:怎么设计得更好
```

默认模板偏向 C++ 那类"要编译、有多线程、有进程间通信"的项目。**前端、数据脚本、库这类项目必须按对照表替换或跳过对应篇目**,见 [reference/project-types.md](reference/project-types.md)。

**编号固定,跳过的留空号,不要往前挪。** 跳过 05 就是 `01,02,03,04,06,07,08,09`,原因见 project-types.md。

---

## Phase 3:写

### 贴代码前先读那个文件

`.project-map.md` 里只有路径,不是代码原文。要贴哪段代码,先 Read 那个文件确认现在的内容。引用统一带位置:`src/core/channel.cpp:120-135`。

不这样做,新人会照着一个不存在的类名去搜索——比没有文档更糟。

### 写给谁看

刚接触项目的新同学。不假设他们了解项目背景,但假设有基础编程能力。

### 每篇都要有的

- 开头一个 `> 一句话说明这篇解决什么问题`
- 先说"是什么" → 再说"为什么" → 最后说"怎么做"
- 有对比(❌ 不用框架怎么写 vs ✅ 用框架怎么写)
- 抽象的概念配一个生活里的例子
- 结尾一张速查表或检查清单

### 图怎么画

| 要表达什么 | 用什么 |
|---|---|
| 调用关系、时序、状态变化、类之间的继承 | **Mermaid** |
| 目录树、分层框图、内存布局 | **ASCII** |

ASCII 图宽度控制在 80 字符内,超了在 Typora 和网页里会折行错位。

### 多长

每篇 **300–600 行**。不到 300 说明挖得不够深;超过 600 该拆节。避免一篇两千行、另一篇三十行。

### 用词

同一个东西前后用同一个词,都按 `.project-map.md` 里的术语表来。在一篇里叫"通道"、另一篇里叫"管道",是新人最容易卡住的地方。

不要生造名词。能用大白话说清的地方不要起一个新词让读者去记。

### 不要

- "如上所述"、"综上"这类套话
- 读者已经知道的废话
- 编造代码,见上面第一条
- 术语第一次出现不解释
- 命令和示例没实际跑过却不说明——跑不了的标 `⚠️ 未验证`

各篇模板:[reference/chapters-01-04.md](reference/chapters-01-04.md)、[reference/chapters-05-09.md](reference/chapters-05-09.md)。

---

## Phase 4:写目录页,然后自查

1. 写 `docs/README.md`,列出所有篇目,说明**不同目的该读哪几篇**,跳过的篇目写明原因。模板见 [reference/quality.md](reference/quality.md)
2. 每篇对着 quality.md 里的清单过一遍
3. 跟用户说清四件事:写了哪几篇各多少行、跳过哪几篇为什么、哪些内容标了 `⚠️ 未验证`、`.project-map.md` 里还剩什么没弄清。后两条最容易漏,但正是用户判断能不能直接把文档给新人看的依据
Pliki w paczce (6)
  • SKILL.md 6 KB
  • reference/chapters-01-04.md 6 KB
  • reference/chapters-05-09.md 6 KB
  • reference/explore.md 4 KB
  • reference/project-types.md 4 KB
  • reference/quality.md 3 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · xstongxue/best-skills100Apache-2.0
coco-research/coco100MIT
nasrulhazim/claude100MIT
event4u-app/agent-config100MIT
GGaryyy/POBG100MIT
DPatta/project-docs-kit100MIT
DPatta/project-docs-kit100MIT
jezweb/claude-skills100MIT
waynesutton/builder-skills100Apache-2.0

Migawka bazy z 13.11.2026 · wersja paczki 51b7bcf9495a (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100codebase-onboarding-skill
    Skanuje kod bieżącego workspace'u i generuje dwa dokumenty dla nowych osób, szybki start i opis architektury, z diagramem Mermaid, tabelą modułów, ścieżką czytania kodu i typowymi pułapkami.
  • 100s04-12-readme-doc
    Pisze README i lokalną instrukcję dla deweloperów: start, debugowanie i częste problemy, dla nowych osób w zespole.
  • 100design-doc
    Pisze dokument z opisem, jak zbudowany jest projekt: główne wybory projektowe i listę plików do czytania dla nowych osób.
  • 90design-review
    Przegląda i poprawia dokument projektowy, w tym jego status, w katalogu docs/design lub w folderze eksperymentów.
  • 100source-reading-analyst
    Pomaga zrozumieć istniejący kod: strukturę, miejsce implementacji funkcji, łańcuch wywołań i przepływ danych przed refaktoryzacją.
  • 100create-doc
    Tworzy nowy plik dokumentacji w .chalk/docs/, gdy użytkownik prosi o napisanie lub dodanie dokumentacji.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.