catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-10 02:24:35 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: 更新文档，增强文档生成工具的使用说明

Browse Source
This commit is contained in:
catlog22
2025-10-22 21:22:04 +08:00
parent 632a6e474a
commit 6fdcf9b8cc
1 changed files with 100 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files

184
.claude/commands/memory/docs.md
View File

@@ -9,9 +9,10 @@ argument-hint: "[path] [--tool <gemini|qwen|codex>] [--mode <full|partial>] [--c
## Overview ## Overview
Lightweight planner that analyzes project structure, decomposes documentation work into tasks, and generates execution plans. Does NOT generate documentation content itself - delegates to doc-generator agent. Lightweight planner that analyzes project structure, decomposes documentation work into tasks, and generates execution plans. Does NOT generate documentation content itself - delegates to doc-generator agent.
**Documentation Output**: All generated documentation is placed in `.workflow/docs/` directory with **mirrored project structure**. For example: **Documentation Output**: All generated documentation is placed in `.workflow/docs/{project_name}/` directory with **mirrored project structure**. For example:
- Source: `src/modules/auth/index.ts` → Docs: `.workflow/docs/src/modules/auth/API.md` - Project: `my_app`
- Source: `lib/core/utils.js` → Docs: `.workflow/docs/lib/core/README.md` - Source: `my_app/src/core/` → Docs: `.workflow/docs/my_app/src/core/API.md`
- Source: `my_app/src/modules/auth/` → Docs: `.workflow/docs/my_app/src/modules/auth/API.md`
**Two Execution Modes**: **Two Execution Modes**:
- **Default**: CLI analyzes in `pre_analysis` (MODE=analysis), agent writes docs in `implementation_approach` - **Default**: CLI analyzes in `pre_analysis` (MODE=analysis), agent writes docs in `implementation_approach`
@@ -19,14 +20,13 @@ Lightweight planner that analyzes project structure, decomposes documentation wo
## Path Mirroring Strategy ## Path Mirroring Strategy
**Principle**: Documentation structure **mirrors** source code structure. **Principle**: Documentation structure **mirrors** source code structure under project-specific directory.
| Source Path | Documentation Path | | Source Path | Project Name | Documentation Path |
|------------|-------------------| |------------|--------------|-------------------|
| `src/modules/auth/index.ts` | `.workflow/docs/src/modules/auth/API.md` | | `my_app/src/core/` | `my_app` | `.workflow/docs/my_app/src/core/API.md` |
| `src/modules/auth/middleware/` | `.workflow/docs/src/modules/auth/middleware/README.md` | | `my_app/src/modules/auth/` | `my_app` | `.workflow/docs/my_app/src/modules/auth/API.md` |
| `lib/core/utils.js` | `.workflow/docs/lib/core/API.md` | | `another_project/lib/utils/` | `another_project` | `.workflow/docs/another_project/lib/utils/API.md` |
| `lib/core/helpers/` | `.workflow/docs/lib/core/helpers/README.md` |
**Benefits**: **Benefits**:
- Easy to locate documentation for any source file - Easy to locate documentation for any source file
@@ -92,6 +92,9 @@ bash(
target_path=$(cd "$path" 2>/dev/null && pwd || echo "$PWD/$path") target_path=$(cd "$path" 2>/dev/null && pwd || echo "$PWD/$path")
fi fi
# Extract project name from target_path
project_name=$(basename "$target_path")
# Create session # Create session
timestamp=$(date +%Y%m%d-%H%M%S) timestamp=$(date +%Y%m%d-%H%M%S)
session="WFS-docs-${timestamp}" session="WFS-docs-${timestamp}"
@@ -106,6 +109,7 @@ bash(
"path": "${path}", "path": "${path}",
"target_path": "${target_path}", "target_path": "${target_path}",
"project_root": "${project_root}", "project_root": "${project_root}",
"project_name": "${project_name}",
"mode": "${mode}", "mode": "${mode}",
"tool": "${tool}", "tool": "${tool}",
"cli_generate": ${cli_generate} "cli_generate": ${cli_generate}
@@ -191,41 +195,48 @@ bash(jq '. + {analysis: {total: "15", code: "8", navigation: "7", top_level: "3"
### Phase 3: Detect Update Mode ### Phase 3: Detect Update Mode
#### Step 1: Count Existing Documentation in .workflow/docs/ #### Step 1: Count Existing Documentation in .workflow/docs/{project_name}/
```bash ```bash
# Check .workflow/docs/ directory and count existing files # Check .workflow/docs/{project_name}/ directory and count existing files
bash(if [[ -d ".workflow/docs" ]]; then bash(
find .workflow/docs -name "*.md" 2>/dev/null | wc -l project_name=$(jq -r '.project_name' .workflow/WFS-docs-20240120/.process/config.json)
else if [[ -d ".workflow/docs/${project_name}" ]]; then
echo "0" find .workflow/docs/${project_name} -name "*.md" 2>/dev/null | wc -l
fi) else
echo "0"
fi
)
``` ```
**Output**: `5` (existing docs in .workflow/docs/) **Output**: `5` (existing docs in .workflow/docs/{project_name}/)
#### Step 2: List Existing Documentation #### Step 2: List Existing Documentation
```bash ```bash
# List existing files in .workflow/docs/ (for task context) # List existing files in .workflow/docs/{project_name}/ (for task context)
bash(if [[ -d ".workflow/docs" ]]; then bash(
find .workflow/docs -name "*.md" 2>/dev/null > .workflow/WFS-docs-20240120/.process/existing-docs.txt project_name=$(jq -r '.project_name' .workflow/WFS-docs-20240120/.process/config.json)
else if [[ -d ".workflow/docs/${project_name}" ]]; then
touch .workflow/WFS-docs-20240120/.process/existing-docs.txt find .workflow/docs/${project_name} -name "*.md" 2>/dev/null > .workflow/WFS-docs-20240120/.process/existing-docs.txt
fi) else
touch .workflow/WFS-docs-20240120/.process/existing-docs.txt
fi
)
``` ```
**Output** (existing-docs.txt): **Output** (existing-docs.txt):
``` ```
.workflow/docs/src/modules/auth/API.md .workflow/docs/my_app/src/modules/auth/API.md
.workflow/docs/src/modules/auth/README.md .workflow/docs/my_app/src/modules/auth/README.md
.workflow/docs/lib/core/README.md .workflow/docs/my_app/lib/core/README.md
.workflow/docs/README.md .workflow/docs/my_app/README.md
``` ```
#### Step 3: Update Config with Update Status #### Step 3: Update Config with Update Status
```bash ```bash
# Determine update status (create or update) and update config # Determine update status (create or update) and update config
bash( bash(
existing_count=$(find .workflow/docs -name "*.md" 2>/dev/null | wc -l) project_name=$(jq -r '.project_name' .workflow/WFS-docs-20240120/.process/config.json)
existing_count=$(find .workflow/docs/${project_name} -name "*.md" 2>/dev/null | wc -l)
if [[ $existing_count -gt 0 ]]; then if [[ $existing_count -gt 0 ]]; then
jq ". + {update_mode: \"update\", existing_docs: $existing_count}" .workflow/WFS-docs-20240120/.process/config.json > .workflow/WFS-docs-20240120/.process/config.json.tmp && mv .workflow/WFS-docs-20240120/.process/config.json.tmp .workflow/WFS-docs-20240120/.process/config.json jq ". + {update_mode: \"update\", existing_docs: $existing_count}" .workflow/WFS-docs-20240120/.process/config.json > .workflow/WFS-docs-20240120/.process/config.json.tmp && mv .workflow/WFS-docs-20240120/.process/config.json.tmp .workflow/WFS-docs-20240120/.process/config.json
else else
@@ -362,7 +373,10 @@ bash(
### Level 1: Module Tree Task ### Level 1: Module Tree Task
**Path Mapping**: Source `src/modules/` → Output `.workflow/docs/src/modules/` **Path Mapping**:
- Project: `{project_name}` (extracted from target_path)
- Source: `{project_name}/src/modules/`
- Output: `.workflow/docs/{project_name}/src/modules/`
**Default Mode (cli_generate=false)**: **Default Mode (cli_generate=false)**:
```json ```json
@@ -376,12 +390,12 @@ bash(
"tool": "gemini", "tool": "gemini",
"cli_generate": false, "cli_generate": false,
"source_path": "src/modules", "source_path": "src/modules",
"output_path": ".workflow/docs/src/modules" "output_path": ".workflow/docs/${project_name}/src/modules"
}, },
"context": { "context": {
"requirements": [ "requirements": [
"Analyze source code in src/modules/", "Analyze source code in src/modules/",
"Generate docs to .workflow/docs/src/modules/ (mirrored structure)", "Generate docs to .workflow/docs/${project_name}/src/modules/ (mirrored structure)",
"For code folders: generate API.md + README.md", "For code folders: generate API.md + README.md",
"For navigation folders: generate README.md only" "For navigation folders: generate README.md only"
], ],
@@ -392,7 +406,7 @@ bash(
"pre_analysis": [ "pre_analysis": [
{ {
"step": "load_existing_docs", "step": "load_existing_docs",
"command": "bash(find .workflow/docs/${top_dir} -name '*.md' 2>/dev/null | xargs cat || echo 'No existing docs')", "command": "bash(find .workflow/docs/${project_name}/${top_dir} -name '*.md' 2>/dev/null | xargs cat || echo 'No existing docs')",
"output_to": "existing_module_docs" "output_to": "existing_module_docs"
}, },
{ {
@@ -415,7 +429,7 @@ bash(
"modification_points": [ "modification_points": [
"Parse folder types from [target_folders]", "Parse folder types from [target_folders]",
"Parse structure from [tree_outline]", "Parse structure from [tree_outline]",
"For src/modules/auth/ → write to .workflow/docs/src/modules/auth/", "For src/modules/auth/ → write to .workflow/docs/${project_name}/src/modules/auth/",
"Generate API.md for code folders", "Generate API.md for code folders",
"Generate README.md for all folders" "Generate README.md for all folders"
], ],
@@ -423,7 +437,7 @@ bash(
"Parse [target_folders] to get folder types", "Parse [target_folders] to get folder types",
"Parse [tree_outline] for structure", "Parse [tree_outline] for structure",
"For each folder in source:", "For each folder in source:",
" - Map source_path to .workflow/docs/{source_path}", " - Map source_path to .workflow/docs/${project_name}/{source_path}",
" - If type == 'code': Generate API.md + README.md", " - If type == 'code': Generate API.md + README.md",
" - Elif type == 'navigation': Generate README.md only" " - Elif type == 'navigation': Generate README.md only"
], ],
@@ -432,8 +446,8 @@ bash(
} }
], ],
"target_files": [ "target_files": [
".workflow/docs/${top_dir}/*/API.md", ".workflow/docs/${project_name}/${top_dir}/*/API.md",
".workflow/docs/${top_dir}/*/README.md" ".workflow/docs/${project_name}/${top_dir}/*/README.md"
] ]
} }
} }
@@ -451,12 +465,12 @@ bash(
"tool": "gemini", "tool": "gemini",
"cli_generate": true, "cli_generate": true,
"source_path": "src/modules", "source_path": "src/modules",
"output_path": ".workflow/docs/src/modules" "output_path": ".workflow/docs/${project_name}/src/modules"
}, },
"context": { "context": {
"requirements": [ "requirements": [
"Analyze source code in src/modules/", "Analyze source code in src/modules/",
"Generate docs to .workflow/docs/src/modules/ (mirrored structure)", "Generate docs to .workflow/docs/${project_name}/src/modules/ (mirrored structure)",
"CLI generates documentation files directly" "CLI generates documentation files directly"
], ],
"focus_paths": ["src/modules"] "focus_paths": ["src/modules"]
@@ -465,7 +479,7 @@ bash(
"pre_analysis": [ "pre_analysis": [
{ {
"step": "load_existing_docs", "step": "load_existing_docs",
"command": "bash(find .workflow/docs/${top_dir} -name '*.md' 2>/dev/null | xargs cat || echo 'No existing docs')", "command": "bash(find .workflow/docs/${project_name}/${top_dir} -name '*.md' 2>/dev/null | xargs cat || echo 'No existing docs')",
"output_to": "existing_module_docs" "output_to": "existing_module_docs"
}, },
{ {
@@ -490,22 +504,22 @@ bash(
"description": "Call CLI to generate docs to .workflow/docs/ with mirrored structure using MODE=write", "description": "Call CLI to generate docs to .workflow/docs/ with mirrored structure using MODE=write",
"modification_points": [ "modification_points": [
"Execute CLI generation command", "Execute CLI generation command",
"Generate files to .workflow/docs/src/modules/ (mirrored path)", "Generate files to .workflow/docs/${project_name}/src/modules/ (mirrored path)",
"Generate API.md and README.md files" "Generate API.md and README.md files"
], ],
"logic_flow": [ "logic_flow": [
"CLI analyzes source code in src/modules/", "CLI analyzes source code in src/modules/",
"CLI writes documentation to .workflow/docs/src/modules/", "CLI writes documentation to .workflow/docs/${project_name}/src/modules/",
"Maintains directory structure mirroring" "Maintains directory structure mirroring"
], ],
"command": "bash(cd src/modules && gemini --approval-mode yolo \"PURPOSE: Generate module docs\\nTASK: Create documentation files in .workflow/docs/src/modules/\\nMODE: write\\nCONTEXT: @**/* [target_folders] [existing_module_docs]\\nEXPECTED: API.md and README.md in .workflow/docs/src/modules/\\nRULES: Mirror source structure, generate complete docs\")", "command": "bash(cd src/modules && gemini --approval-mode yolo \"PURPOSE: Generate module docs\\nTASK: Create documentation files in .workflow/docs/${project_name}/src/modules/\\nMODE: write\\nCONTEXT: @**/* [target_folders] [existing_module_docs]\\nEXPECTED: API.md and README.md in .workflow/docs/${project_name}/src/modules/\\nRULES: Mirror source structure, generate complete docs\")",
"depends_on": [1], "depends_on": [1],
"output": "generated_docs" "output": "generated_docs"
} }
], ],
"target_files": [ "target_files": [
".workflow/docs/${top_dir}/*/API.md", ".workflow/docs/${project_name}/${top_dir}/*/API.md",
".workflow/docs/${top_dir}/*/README.md" ".workflow/docs/${project_name}/${top_dir}/*/README.md"
] ]
} }
} }
@@ -530,12 +544,12 @@ bash(
"pre_analysis": [ "pre_analysis": [
{ {
"step": "load_existing_readme", "step": "load_existing_readme",
"command": "bash(cat .workflow/docs/README.md 2>/dev/null || echo 'No existing README')", "command": "bash(cat .workflow/docs/${project_name}/README.md 2>/dev/null || echo 'No existing README')",
"output_to": "existing_readme" "output_to": "existing_readme"
}, },
{ {
"step": "load_module_docs", "step": "load_module_docs",
"command": "bash(find .workflow/docs -type f -name '*.md' ! -path '.workflow/docs/README.md' ! -path '.workflow/docs/ARCHITECTURE.md' ! -path '.workflow/docs/EXAMPLES.md' ! -path '.workflow/docs/api/*' | xargs cat)", "command": "bash(find .workflow/docs/${project_name} -type f -name '*.md' ! -path '.workflow/docs/${project_name}/README.md' ! -path '.workflow/docs/${project_name}/ARCHITECTURE.md' ! -path '.workflow/docs/${project_name}/EXAMPLES.md' ! -path '.workflow/docs/${project_name}/api/*' | xargs cat)",
"output_to": "all_module_docs", "output_to": "all_module_docs",
"note": "Load all module docs from mirrored structure" "note": "Load all module docs from mirrored structure"
}, },
@@ -556,7 +570,7 @@ bash(
"output": "project_readme" "output": "project_readme"
} }
], ],
"target_files": [".workflow/docs/README.md"] "target_files": [".workflow/docs/${project_name}/README.md"]
} }
} }
``` ```
@@ -580,12 +594,12 @@ bash(
"pre_analysis": [ "pre_analysis": [
{ {
"step": "load_existing_docs", "step": "load_existing_docs",
"command": "bash(cat .workflow/docs/ARCHITECTURE.md 2>/dev/null || echo 'No existing ARCHITECTURE'; echo '---SEPARATOR---'; cat .workflow/docs/EXAMPLES.md 2>/dev/null || echo 'No existing EXAMPLES')", "command": "bash(cat .workflow/docs/${project_name}/ARCHITECTURE.md 2>/dev/null || echo 'No existing ARCHITECTURE'; echo '---SEPARATOR---'; cat .workflow/docs/${project_name}/EXAMPLES.md 2>/dev/null || echo 'No existing EXAMPLES')",
"output_to": "existing_arch_examples" "output_to": "existing_arch_examples"
}, },
{ {
"step": "load_all_docs", "step": "load_all_docs",
"command": "bash(cat .workflow/docs/README.md && find .workflow/docs -type f -name '*.md' ! -path '.workflow/docs/README.md' ! -path '.workflow/docs/ARCHITECTURE.md' ! -path '.workflow/docs/EXAMPLES.md' ! -path '.workflow/docs/api/*' | xargs cat)", "command": "bash(cat .workflow/docs/${project_name}/README.md && find .workflow/docs/${project_name} -type f -name '*.md' ! -path '.workflow/docs/${project_name}/README.md' ! -path '.workflow/docs/${project_name}/ARCHITECTURE.md' ! -path '.workflow/docs/${project_name}/EXAMPLES.md' ! -path '.workflow/docs/${project_name}/api/*' | xargs cat)",
"output_to": "all_docs", "output_to": "all_docs",
"note": "Load README + all module docs from mirrored structure" "note": "Load README + all module docs from mirrored structure"
}, },
@@ -617,8 +631,8 @@ bash(
} }
], ],
"target_files": [ "target_files": [
".workflow/docs/ARCHITECTURE.md", ".workflow/docs/${project_name}/ARCHITECTURE.md",
".workflow/docs/EXAMPLES.md" ".workflow/docs/${project_name}/EXAMPLES.md"
] ]
} }
} }
@@ -648,7 +662,7 @@ bash(
}, },
{ {
"step": "load_existing_api_docs", "step": "load_existing_api_docs",
"command": "bash(cat .workflow/docs/api/README.md 2>/dev/null || echo 'No existing API docs')", "command": "bash(cat .workflow/docs/${project_name}/api/README.md 2>/dev/null || echo 'No existing API docs')",
"output_to": "existing_api_docs" "output_to": "existing_api_docs"
}, },
{ {
@@ -668,7 +682,7 @@ bash(
"output": "api_docs" "output": "api_docs"
} }
], ],
"target_files": [".workflow/docs/api/README.md"] "target_files": [".workflow/docs/${project_name}/api/README.md"]
} }
} }
``` ```
@@ -701,8 +715,9 @@ bash(
"session_id": "WFS-docs-20240120-143022", "session_id": "WFS-docs-20240120-143022",
"timestamp": "2024-01-20T14:30:22+08:00", "timestamp": "2024-01-20T14:30:22+08:00",
"path": ".", "path": ".",
"target_path": "/d/Claude_dms3", "target_path": "/home/user/projects/my_app",
"project_root": "/d/Claude_dms3", "project_root": "/home/user/projects",
"project_name": "my_app",
"mode": "full", "mode": "full",
"tool": "gemini", "tool": "gemini",
"cli_generate": false, "cli_generate": false,
@@ -719,33 +734,34 @@ bash(
## Generated Documentation ## Generated Documentation
**Structure mirrors project source directories**: **Structure mirrors project source directories under project-specific folder**:
``` ```
.workflow/docs/ .workflow/docs/
├── src/ # Mirrors src/ directory └── {project_name}/ # Project-specific root (e.g., my_app/)
│ ├── modules/ # Level 1 output ├── src/ # Mirrors src/ directory
│ │ ├── README.md # Navigation for src/modules/ │ ├── modules/ # Level 1 output
│ │ ├── auth/ │ │ ├── README.md # Navigation for src/modules/
│ │ │ ├── API.md # Auth module API signatures │ │ ├── auth/
│ │ │ ├── README.md # Auth module documentation │ │ │ ├── API.md # Auth module API signatures
│ │ │ └── middleware/ │ │ │ ├── README.md # Auth module documentation
│ │ │ ├── API.md # Middleware API │ │ │ └── middleware/
│ │ │ └── README.md # Middleware docs │ │ │ ├── API.md # Middleware API
│ │ └── api/ │ │ │ └── README.md # Middleware docs
│ │ ├── API.md # API module signatures │ │ └── api/
│ │ └── README.md # API module docs │ │ ├── API.md # API module signatures
│ └── utils/ # Level 1 output │ │ └── README.md # API module docs
│ └── README.md # Utils navigation │ └── utils/ # Level 1 output
├── lib/ # Mirrors lib/ directory │ └── README.md # Utils navigation
│ └── core/ ├── lib/ # Mirrors lib/ directory
│ ├── API.md │ └── core/
│ └── README.md │ ├── API.md
├── README.md # Level 2 output (root only) │ └── README.md
├── ARCHITECTURE.md # Level 3 output (root only) ├── README.md # Level 2 output (project root only)
├── EXAMPLES.md # Level 3 output (root only) ├── ARCHITECTURE.md # Level 3 output (project root only)
└── api/ # Level 3 output (optional) ├── EXAMPLES.md # Level 3 output (project root only)
└── README.md # HTTP API reference └── api/ # Level 3 output (optional)
└── README.md # HTTP API reference
``` ```
## Execution Commands ## Execution Commands
@@ -792,11 +808,11 @@ bash(ls .workflow/WFS-docs-20240120/.task/*.json)
# Discover and classify folders (scans project source) # Discover and classify folders (scans project source)
bash(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-folders.sh) bash(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-folders.sh)
# Count existing docs (in .workflow/docs/ directory) # Count existing docs (in .workflow/docs/{project_name}/ directory)
bash(if [[ -d ".workflow/docs" ]]; then find .workflow/docs -name "*.md" 2>/dev/null | wc -l; else echo "0"; fi) bash(if [[ -d ".workflow/docs/${project_name}" ]]; then find .workflow/docs/${project_name} -name "*.md" 2>/dev/null | wc -l; else echo "0"; fi)
# List existing documentation (in .workflow/docs/ directory) # List existing documentation (in .workflow/docs/{project_name}/ directory)
bash(if [[ -d ".workflow/docs" ]]; then find .workflow/docs -name "*.md" 2>/dev/null; fi) bash(if [[ -d ".workflow/docs/${project_name}" ]]; then find .workflow/docs/${project_name} -name "*.md" 2>/dev/null; fi)
``` ```
## Template Reference ## Template Reference