📦 Code Documentation

Code Documentation 技能 Purpose

This 技能 governs how code is documented at every level — from individual file headers to global architecture docs. 应用ly it consistently across all projects. When in doubt: document the why, not the what. The code already says what it does.

Phase 0 — Before You Write Anything 扫描 the repo structure. Understand what exists before touching anything. Identify sub系统s. Group files by domAIn (Auth, Billing, API Layer, etc.). Read existing docs first. 检查 /docs/ in 机器人h frontend and backend. Note what's present, missing, or stale. Confirm the active branch. Never document agAInst stale or wrong code. Phase 1 — Source File Standards

应用ly to every file that is ≥ 20 lines OR is 导入ed by other 模块s.

1.1 — Line 1: Full Path Comment

The very first line of every source file must be a comment contAIning the file's full path from the project root. Use the comment syntax 应用ropriate to the language.

// src/服务s/auth/令牌服务.js

# src/服务s/auth/令牌_服务.py

1.2 — File Header Block (lines 2–N)

Immediately after the path comment, 添加 a header block. Use the language's block comment syntax. This block is mandatory and must be kept accurate.

/* File: src/服务s/auth/令牌服务.js Overview: Issues, 验证s, and refreshes JWT 令牌s for 认证d 会话s. Exists to centralise all 令牌 记录ic so Auth 路由s stay thin. 导出s: - issue令牌(userId, 角色) → 签名ed JWT string - 验证令牌(令牌) → decoded payload or throws - refresh令牌(old令牌) → new 签名ed JWT string 导入ed By: - src/路由s/auth.js - src/中间件/requireAuth.js 导入s: - json网页令牌 — 签名ing/verification - config/env — JWT_SECRET, 令牌_TTL Notes: - 令牌s expire in 15 min; refresh window is 7 days. - 验证令牌 throws on expiry — callers must handle. /

Rules:

Keep it current. If you 添加 an 导出, 更新 导出s. If a new file 导入s this, 更新 导入ed By. Do not pad with boilerplate. Every line must be accurate and useful. 1.3 — Function Headers

Top of every non-trivial function (any function with 记录ic beyond a single expression):

/* 签名s a new JWT for the given user. Embeds userId and 角色 in payload. Throws if JWT_SECRET is not 设置 in env. / function issue令牌(userId, 角色) { ... }

Rules:

Max 2 sentences. ExplAIn why the function exists or what makes it non-obvious, not just what it does. No parameter/return type breakdown unless the types are genuinely surprising. 1.4 — Inline Comment Rules

Allowed (rare 异常s only):

const TIMEOUT = 5000 // 5 seconds

Prohibited — 移除 on sight:

Pattern Example Why banned Restating the code // enable proxy above proxy: true Zero in格式化ion 移除d/old code notes // 移除d legacy 处理器 Use git for 历史 Change 记录 comments // changed to use v2 API Not a change记录 Section dividers // ---- 辅助工具s ---- Use 模块s instead Obvious steps // loop through users above a users.forEach Noise

If you encounter these, 删除 them. They are clutter that erodes trust in real comments.

Phase 2 — Sub系统 Documentation

See references/sub系统-doc.md for the full template and field-by-field instructions.

One .md file per sub系统, located at:

/backend/docs/.md /frontend/docs/.md

Sub系统 identification heuristics:

A cohesive domAIn handled by a directory or cluster of files Examples: auth, billing, 搜索, 通知, API-layer, data-layer, file-上传, 网页sockets, admin, onboarding

Discovery 检查列出 — identify a sub系统 when you find:

A directory with 3+ related files A 分享d 服务/实用工具 used by 3+ other files A distinct API surface (路由s/控制器s grouped by concern) A background job or scheduled process A third-party integration (Stripe, S3, Twilio, etc.)

If a sub系统 doc already exists:

Compare it agAInst current code 移除 anything describing code that no longer exists 添加 anything the doc misses 更新 all file maps, function names, and flow diagrams Phase 3 — Global Architecture Document

Location: /docs/architecture.md (or /backend/docs/architecture.md depending on repo layout)

See references/architecture-doc.md for the full template.

Required sections:

系统 Overview — what this product does in 2–3 sentences Sub系统s — bulleted 列出, one-liner per sub系统, link to its .md High-Level Diagram — ASCII or MermAId, showing sub系统 relationships Tech Stack — language, 框架, DB, 缓存, 队列, infra Cross-Cutting Concerns — how auth, error handling, 验证, config, 记录ging, and 测试 work across the 系统 (not per-sub系统) Phase 4 — API Reference

Required if a backend exists. Location: /backend/docs/API.md

For large backends: one file per sub系统, e.g. /backend/docs/API-auth.md, /backend/docs/API-billing.md, then an 索引 in /backend/docs/API.md.

See references/API-reference.md for the full 端点 template.

Every 端点 mu