documentation-audit

文档审计

概述

检测到文档与代码不一致时，全面同步文档。分析代码库，并创建或更新所有文档资料，使其与代码库完全同步。

核心原则： 文档必须反映实际情况。此技能可使文档与实际情况保持一致。

开始时先说明：“我正在使用 documentation-audit 同步所有文档，使其与当前代码库保持一致。”

此技能的触发条件

以下情况会调用此技能：

触发条件	来源
API 文档不一致	api-documentation 技能
功能文档不一致	features-documentation 技能
缺少文档文件	任意文档检查
手动请求	用户或协调器

审计流程

阶段 1：发现

echo "=== Documentation Audit: Discovery Phase ==="

# Find all documentation files
DOC_FILES=$(find . -name "*.md" -o -name "*.yaml" -o -name "*.json" | \
  grep -E "(doc|api|swagger|openapi|feature|guide|readme)" | \
  grep -v node_modules | grep -v .git)

echo "Found documentation files:"
echo "$DOC_FILES"

# Find API documentation
API_DOC=$(find . -name "openapi.yaml" -o -name "swagger.yaml" -o -name "openapi.json" | head -1)
echo "API Documentation: ${API_DOC:-MISSING}"

# Find features documentation
FEATURE_DOC=$(find . -name "features.md" -o -name "FEATURES.md" | head -1)
echo "Features Documentation: ${FEATURE_DOC:-MISSING}"

阶段 2：API 审计

如果存在 API 端点：

echo "=== Documentation Audit: API Phase ==="

# Detect API framework
detect_api_framework() {
  if grep -r "express" package.json 2>/dev/null; then echo "express"; return; fi
  if grep -r "fastify" package.json 2>/dev/null; then echo "fastify"; return; fi
  if grep -r "@nestjs" package.json 2>/dev/null; then echo "nestjs"; return; fi
  if grep -r "fastapi" requirements.txt 2>/dev/null; then echo "fastapi"; return; fi
  if grep -r "flask" requirements.txt 2>/dev/null; then echo "flask"; return; fi
  if [ -f "go.mod" ]; then echo "go"; return; fi
  echo "unknown"
}

FRAMEWORK=$(detect_api_framework)
echo "Detected framework: $FRAMEWORK"

# Extract all endpoints from code
extract_endpoints() {
  case "$FRAMEWORK" in
    express|fastify)
      grep -rh "app\.\(get\|post\|put\|delete\|patch\)" --include="*.ts" --include="*.js" | \
        sed "s/.*app\.\([a-z]*\)('\([^']*\)'.*/\1 \2/"
      ;;
    nestjs)
      grep -rh "@\(Get\|Post\|Put\|Delete\|Patch\)" --include="*.ts" | \
        sed "s/.*@\([A-Za-z]*\)('\([^']*\)'.*/\1 \2/"
      ;;
    fastapi)
      grep -rh "@app\.\(get\|post\|put\|delete\|patch\)" --include="*.py" | \
        sed "s/.*@app\.\([a-z]*\)(\"\([^\"]*\)\".*/\1 \2/"
      ;;
    *)
      echo "Unknown framework - manual inspection required"
      ;;
  esac
}

ENDPOINTS=$(extract_endpoints)
echo "Found endpoints:"
echo "$ENDPOINTS"

阶段 3：功能审计

echo "=== Documentation Audit: Features Phase ==="

# Find user-facing components
find_features() {
  # React components in pages/views
  find . -path "*/pages/*" -name "*.tsx" -o -path "*/views/*" -name "*.tsx" | \
    xargs -I {} basename {} .tsx 2>/dev/null

  # Feature flags
  grep -rh "featureFlag\|feature:" --include="*.ts" --include="*.tsx" | \
    sed "s/.*['\"]feature[':]\s*['\"]?\([^'\"]*\)['\"]?.*/\1/" 2>/dev/null

  # Config options exposed to users
  grep -rh "config\.\|settings\." --include="*.ts" | \
    grep -v "import\|require" | \
    sed "s/.*\(config\|settings\)\.\([a-zA-Z]*\).*/\2/" 2>/dev/null | sort -u
}

FEATURES=$(find_features)
echo "Discovered features:"
echo "$FEATURES"

阶段 4：生成缺失的文档

缺少 OpenAPI 时创建

# Template for new OpenAPI file
openapi: 3.0.3
info:
  title: [PROJECT_NAME] API
  description: |
    API documentation for [PROJECT_NAME].
    Generated by documentation-audit skill.
  version: 1.0.0
  contact:
    name: API Support
servers:
  - url: http://localhost:3000
    description: Development server
  - url: https://api.example.com
    description: Production server
paths:
  # Endpoints will be added here
components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

缺少功能文档时创建

# Features

> Generated by documentation-audit skill. Update with accurate descriptions.

## Overview

[Brief description of the product]

## Core Features

### [Feature 1]

**Description:** [What it does]

**How to Use:**
1. [Step 1]
2. [Step 2]

---

## Additional Features

[List additional features discovered]

---

*Last updated: [DATE]*
*Note: This file was auto-generated. Review and enhance descriptions.*

阶段 5：更新现有文档

对于每个已发现但未记录的项目：

1. API 端点 — 在 OpenAPI 规范中添加：

   • 路径和方法
   • 参数（来自函数签名）
   • 请求体架构（来自 DTO/类型）
   • 响应架构（来自返回类型）
   • 基本说明

2. 功能 — 在功能文档中添加：

   • 功能名称
   • 基本说明
   • 如何使用的占位内容
   • 提醒审阅并完善的注释

阶段 6：验证

echo "=== Documentation Audit: Validation Phase ==="

# Validate OpenAPI
if [ -f "openapi.yaml" ]; then
  yq '.' openapi.yaml > /dev/null 2>&1 && echo "OpenAPI: Valid YAML" || echo "OpenAPI: Invalid YAML"
fi

# Validate Markdown
for file in docs/*.md; do
  if [ -f "$file" ]; then
    # Check for required sections
    if ! grep -q "^## " "$file"; then
      echo "WARNING: $file missing section headers"
    fi
  fi
done

# Check completeness
ENDPOINTS_DOCUMENTED=$(yq '.paths | keys | length' openapi.yaml 2>/dev/null || echo 0)
ENDPOINTS_IN_CODE=$(extract_endpoints | wc -l)

echo "Endpoints in code: $ENDPOINTS_IN_CODE"
echo "Endpoints documented: $ENDPOINTS_DOCUMENTED"

if [ "$ENDPOINTS_DOCUMENTED" -lt "$ENDPOINTS_IN_CODE" ]; then
  echo "WARNING: Some endpoints still undocumented"
fi

审计报告

将审计结果发布到 GitHub issue：

## Documentation Audit Complete

**Audit Date:** [ISO_TIMESTAMP]
**Triggered By:** [api-documentation|features-documentation|manual]

### Summary

| Category | Before | After | Status |
|----------|--------|-------|--------|
| API Endpoints | [N] undocumented | [N] documented | [COMPLETE/PARTIAL] |
| Features | [N] undocumented | [N] documented | [COMPLETE/PARTIAL] |
| General Docs | [N] missing | [N] created | [COMPLETE/PARTIAL] |

### Files Created
- `openapi.yaml` - API documentation
- `docs/features.md` - Features documentation

### Files Updated
- `openapi.yaml` - Added [N] endpoints
- `docs/features.md` - Added [N] features

### Requires Manual Review
- [ ] Verify API response schemas
- [ ] Enhance feature descriptions
- [ ] Add usage examples
- [ ] Review security documentation

### Next Steps
1. Review generated documentation
2. Add detailed descriptions
3. Include examples
4. Validate with stakeholders

---
*documentation-audit skill completed*

检查清单

审计期间：

• 已发现所有文档文件
• 已检测 API 框架
• 已从代码中提取所有端点
• 已从代码中提取所有功能
• 已创建缺失的文档文件
• 已更新现有文档
• 已验证所有文件
• 已将审计报告发布到 issue
• 已提交更改

质量标准

生成的文档必须符合以下要求：

标准	要求
完整性	列出每个端点/功能
有效性	YAML/JSON 验证通过
结构	包含必需章节
占位内容	提供清晰的手动审阅标记
归属说明	注明由技能生成

集成

调用此技能的场景：

技能	时机
api-documentation	检测到 API 不一致时
features-documentation	检测到功能不一致时
issue-driven-development	文档步骤

此技能使用以下工具：

工具	用途
Glob/Grep	发现代码资料
Read	分析现有文档
Write	创建新文档
Edit	更新现有文档
yq	验证 YAML
jq	验证 JSON