mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-18 18:48:48 +08:00
feat: enhance search, ranking, reranker and CLI tooling across ccw and codex-lens
Major improvements to smart-search, chain-search cascade, ranking pipeline, reranker factory, CLI history store, codex-lens integration, and uv-manager. Simplify command-generator skill by inlining phases. Add comprehensive tests. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
catlog22
@@ -1,160 +1,65 @@
|
||||
# Command Design Specification
|
||||
|
||||
Guidelines and best practices for designing Claude Code command files.
|
||||
Guidelines for Claude Code command files generated by command-generator.
|
||||
|
||||
## Command File Structure
|
||||
|
||||
### YAML Frontmatter
|
||||
|
||||
Every command file must start with YAML frontmatter containing:
|
||||
## YAML Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: command-name # Required: Command identifier (lowercase, hyphens)
|
||||
description: Description # Required: Brief description of command purpose
|
||||
argument-hint: "[args]" # Optional: Argument format hint
|
||||
allowed-tools: Tool1, Tool2 # Optional: Restricted tool set
|
||||
examples: # Optional: Usage examples
|
||||
- /command:example1
|
||||
- /command:example2 --flag
|
||||
name: command-name # Required: lowercase with hyphens
|
||||
description: Description # Required: brief purpose
|
||||
argument-hint: "[args]" # Optional: argument format hint
|
||||
allowed-tools: Tool1, Tool2 # Optional: restricted tool set
|
||||
---
|
||||
```
|
||||
|
||||
### Frontmatter Fields
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `name` | Yes | Command identifier, lowercase with hyphens |
|
||||
| `description` | Yes | Brief description, appears in command listings |
|
||||
| `argument-hint` | No | Usage hint for arguments (shown in help) |
|
||||
| `allowed-tools` | No | Restrict available tools for this command |
|
||||
| `examples` | No | Array of usage examples |
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
### Command Names
|
||||
| Element | Convention | Examples |
|
||||
|---------|-----------|----------|
|
||||
| Command name | lowercase, hyphens, 2-3 words max | `deploy`, `create-issue` |
|
||||
| Group name | singular noun | `issue`, `session`, `workflow` |
|
||||
| Verbs for actions | imperative | `deploy`, `create`, `analyze` |
|
||||
|
||||
- Use lowercase letters only
|
||||
- Separate words with hyphens (`create-issue`, not `createIssue`)
|
||||
- Keep names short but descriptive (2-3 words max)
|
||||
- Use verbs for actions (`deploy`, `create`, `analyze`)
|
||||
|
||||
### Group Names
|
||||
|
||||
- Groups organize related commands
|
||||
- Use singular nouns (`issue`, `session`, `workflow`)
|
||||
- Common groups: `issue`, `workflow`, `session`, `memory`, `cli`
|
||||
|
||||
### Path Examples
|
||||
## Path Structure
|
||||
|
||||
```
|
||||
.claude/commands/deploy.md # Top-level command
|
||||
.claude/commands/issue/create.md # Grouped command
|
||||
.claude/commands/workflow/init.md # Grouped command
|
||||
~/.claude/commands/global-status.md # User-level command
|
||||
```
|
||||
|
||||
## Content Sections
|
||||
## Content Structure (GSD Style)
|
||||
|
||||
### Required Sections
|
||||
Generated commands should use XML semantic tags:
|
||||
|
||||
1. **Overview**: Brief description of command purpose
|
||||
2. **Usage**: Command syntax and examples
|
||||
3. **Execution Flow**: High-level process diagram
|
||||
| Tag | Required | Purpose |
|
||||
|-----|----------|---------|
|
||||
| `<purpose>` | Yes | What the command does, when invoked, what it produces |
|
||||
| `<required_reading>` | Yes | Files to read before execution (@ notation) |
|
||||
| `<process>` | Yes | Container for execution steps |
|
||||
| `<step name="...">` | Yes | Individual execution steps with snake_case names |
|
||||
| `<error_codes>` | No | Error code table with severity and description |
|
||||
| `<success_criteria>` | Yes | Checkbox list of verifiable completion conditions |
|
||||
|
||||
### Recommended Sections
|
||||
## Step Naming
|
||||
|
||||
4. **Implementation**: Code examples for each phase
|
||||
5. **Error Handling**: Error cases and recovery
|
||||
6. **Related Commands**: Links to related functionality
|
||||
- Use snake_case: `parse_input`, `validate_config`, `write_output`
|
||||
- Use action verbs: `discover`, `validate`, `spawn`, `collect`, `report`
|
||||
- First step gets `priority="first"` attribute
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Clear Purpose
|
||||
|
||||
Each command should do one thing well:
|
||||
## Error Messages
|
||||
|
||||
```
|
||||
Good: /issue:create - Create a new issue
|
||||
Bad: /issue:manage - Create, update, delete issues (too broad)
|
||||
```
|
||||
Good: Error: GitHub issue URL required
|
||||
Usage: /issue:create <github-url>
|
||||
|
||||
### 2. Consistent Structure
|
||||
|
||||
Follow the same pattern across all commands in a group:
|
||||
|
||||
```markdown
|
||||
# All issue commands should have:
|
||||
- Overview
|
||||
- Usage with examples
|
||||
- Phase-based implementation
|
||||
- Error handling table
|
||||
```
|
||||
|
||||
### 3. Progressive Detail
|
||||
|
||||
Start simple, add detail in phases:
|
||||
|
||||
```
|
||||
Phase 1: Quick overview
|
||||
Phase 2: Implementation details
|
||||
Phase 3: Edge cases and errors
|
||||
```
|
||||
|
||||
### 4. Reusable Patterns
|
||||
|
||||
Use consistent patterns for common operations:
|
||||
|
||||
```javascript
|
||||
// Input parsing pattern
|
||||
const args = parseArguments($ARGUMENTS);
|
||||
const flags = parseFlags($ARGUMENTS);
|
||||
|
||||
// Validation pattern
|
||||
if (!args.required) {
|
||||
throw new Error('Required argument missing');
|
||||
}
|
||||
Bad: Error: Invalid input
|
||||
```
|
||||
|
||||
## Scope Guidelines
|
||||
|
||||
### Project Commands (`.claude/commands/`)
|
||||
|
||||
- Project-specific workflows
|
||||
- Team conventions
|
||||
- Integration with project tools
|
||||
|
||||
### User Commands (`~/.claude/commands/`)
|
||||
|
||||
- Personal productivity tools
|
||||
- Cross-project utilities
|
||||
- Global configuration
|
||||
|
||||
## Error Messages
|
||||
|
||||
### Good Error Messages
|
||||
|
||||
```
|
||||
Error: GitHub issue URL required
|
||||
Usage: /issue:create <github-url>
|
||||
Example: /issue:create https://github.com/owner/repo/issues/123
|
||||
```
|
||||
|
||||
### Bad Error Messages
|
||||
|
||||
```
|
||||
Error: Invalid input
|
||||
```
|
||||
|
||||
## Testing Commands
|
||||
|
||||
After creating a command, test:
|
||||
|
||||
1. **Basic invocation**: Does it run without arguments?
|
||||
2. **Argument parsing**: Does it handle valid arguments?
|
||||
3. **Error cases**: Does it show helpful errors for invalid input?
|
||||
4. **Help text**: Is the usage clear?
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) - Full skill design specification
|
||||
- [../skill-generator/SKILL.md](../skill-generator/SKILL.md) - Meta-skill for creating skills
|
||||
| Scope | Location | Use For |
|
||||
|-------|----------|---------|
|
||||
| Project | `.claude/commands/` | Team workflows, project integrations |
|
||||
| User | `~/.claude/commands/` | Personal tools, cross-project utilities |
|
||||
|
||||
Reference in New Issue
Block a user