mirror of
https://github.com/luongnv89/claude-howto.git
synced 2026-06-10 10:43:54 +02:00
docs: Add blog post and new slash commands for development workflow
- Add blog post: 4 Essential Slash Commands I Use in Every Project - Add new slash commands: /doc-refactor, /setup-ci-cd, /unit-test-expand - Update slash-commands README with comprehensive documentation - Simplify /push-all command structure - Archive add-blog-post-slash-commands change - Add blog-post spec and pending openspec changes
This commit is contained in:
Luong NGUYEN
@@ -284,7 +284,7 @@ sequenceDiagram
|
||||
Claude->>User: Returns analysis
|
||||
```
|
||||
|
||||
## Available Commands in This Folder
|
||||
## Available Commands in This Folder (8 Commands)
|
||||
|
||||
### 1. `/optimize` - Code Optimization
|
||||
Analyzes code for performance issues, memory leaks, and optimization opportunities.
|
||||
@@ -350,6 +350,83 @@ Creates a git commit with dynamic context from your repository.
|
||||
- Uses `allowed-tools` for git operations
|
||||
- Supports optional commit message argument
|
||||
|
||||
### 5. `/push-all` - Stage, Commit, and Push
|
||||
Stages all changes, creates a commit, and pushes to remote with comprehensive safety checks.
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/push-all
|
||||
```
|
||||
|
||||
**Workflow:**
|
||||
1. Analyzes changes (git status, diff, log)
|
||||
2. Runs safety checks for secrets, API keys, large files, build artifacts
|
||||
3. Validates API keys are placeholders (not real credentials)
|
||||
4. Presents summary and requests confirmation
|
||||
5. Stages all changes and generates conventional commit message
|
||||
6. Commits and pushes to remote
|
||||
|
||||
**Safety Checks:**
|
||||
- Secrets: `.env*`, `*.key`, `*.pem`, `credentials.json`, etc.
|
||||
- API Keys: Detects real keys vs. placeholders like `your-api-key-here`
|
||||
- Large files: `>10MB` without Git LFS
|
||||
- Build artifacts: `node_modules/`, `dist/`, `__pycache__/`, etc.
|
||||
|
||||
**Caution:** Use only when confident all changes belong together.
|
||||
|
||||
### 6. `/doc-refactor` - Documentation Restructuring
|
||||
Restructures project documentation for clarity and accessibility, adapting to project type.
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/doc-refactor
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Analyzes project type (library, API, web app, CLI, microservices)
|
||||
- Centralizes documentation in `docs/` folder
|
||||
- Streamlines root README as entry point
|
||||
- Creates component-level documentation
|
||||
- Generates guides based on project needs (User Guide, API Docs, Development Guide)
|
||||
- Uses Mermaid for all diagrams
|
||||
|
||||
### 7. `/setup-ci-cd` - CI/CD Pipeline Setup
|
||||
Implements pre-commit hooks and GitHub Actions for quality assurance.
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/setup-ci-cd
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Detects project language(s), framework, and build system
|
||||
- Configures pre-commit hooks with language-specific tools:
|
||||
- Formatting (Prettier, Black, gofmt, rustfmt)
|
||||
- Linting (ESLint, Ruff, golangci-lint, Clippy)
|
||||
- Security scanning (Bandit, gosec, cargo-audit)
|
||||
- Type checking (TypeScript, mypy)
|
||||
- Creates GitHub Actions workflows in `.github/workflows/`
|
||||
- Verifies pipeline with local tests
|
||||
|
||||
### 8. `/unit-test-expand` - Test Coverage Expansion
|
||||
Increases test coverage by targeting untested branches and edge cases.
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/unit-test-expand
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Analyzes coverage to identify untested branches and low-coverage areas
|
||||
- Identifies gaps: error paths, boundary conditions, null/empty inputs
|
||||
- Generates tests using project's framework (Jest, pytest, Go testing, Rust)
|
||||
- Targets specific scenarios:
|
||||
- Error handling and exceptions
|
||||
- Boundary values (min/max, empty, null)
|
||||
- Edge cases and corner cases
|
||||
- State transitions and side effects
|
||||
- Verifies coverage improvement
|
||||
|
||||
## Installation
|
||||
|
||||
### For Project-wide Use (Team)
|
||||
@@ -486,6 +563,7 @@ Run the project tests with the following options:
|
||||
|
||||
- [Claude Code Slash Commands Documentation](https://code.claude.com/docs/en/slash-commands) - Official documentation
|
||||
- [Discovering Claude Code Slash Commands](https://medium.com/@luongnv89/discovering-claude-code-slash-commands-cdc17f0dfb29) - Comprehensive blog post
|
||||
- [4 Essential Slash Commands I Use in Every Project](../blog-post/4-essential-slash-commands.md) - Practical workflow guide
|
||||
- [Markdown Guide](https://www.markdownguide.org/)
|
||||
|
||||
---
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
---
|
||||
name: Documentation Refactor
|
||||
description: Restructure project documentation for clarity and accessibility
|
||||
tags: documentation, refactoring, organization
|
||||
---
|
||||
|
||||
# Documentation Refactor
|
||||
|
||||
Refactor project documentation structure adapted to project type:
|
||||
|
||||
1. **Analyze project**: Identify type (library/API/web app/CLI/microservices), architecture, and user personas
|
||||
2. **Centralize docs**: Move technical documentation to `docs/` with proper cross-references
|
||||
3. **Root README.md**: Streamline as entry point with overview, quickstart, modules/components summary, license, contacts
|
||||
4. **Component docs**: Add module/package/service-level README files with setup and testing instructions
|
||||
5. **Organize `docs/`** by relevant categories:
|
||||
- Architecture, API Reference, Database, Design, Troubleshooting, Deployment, Contributing (adapt to project needs)
|
||||
6. **Create guides** (select applicable):
|
||||
- User Guide: End-user documentation for applications
|
||||
- API Documentation: Endpoints, authentication, examples for APIs
|
||||
- Development Guide: Setup, testing, contribution workflow
|
||||
- Deployment Guide: Production deployment for services/apps
|
||||
7. **Use Mermaid** for all diagrams (architecture, flows, schemas)
|
||||
|
||||
Keep docs concise, scannable, and contextual to project type.
|
||||
+76
-396
@@ -5,468 +5,148 @@ allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git
|
||||
|
||||
# Commit and Push Everything
|
||||
|
||||
⚠️ **CAUTION**: This command will stage ALL changes, commit them, and push to the remote repository. Use only when you're confident all changes should be committed together.
|
||||
⚠️ **CAUTION**: Stage ALL changes, commit, and push to remote. Use only when confident all changes belong together.
|
||||
|
||||
## Pre-flight Safety Checks
|
||||
## Workflow
|
||||
|
||||
Before proceeding, I will verify:
|
||||
### 1. Analyze Changes
|
||||
Run in parallel:
|
||||
- `git status` - Show modified/added/deleted/untracked files
|
||||
- `git diff --stat` - Show change statistics
|
||||
- `git log -1 --oneline` - Show recent commit for message style
|
||||
|
||||
1. **Current Status**
|
||||
- Run `git status` to see what will be committed
|
||||
- Ensure no unwanted files are included
|
||||
- Verify you're on the correct branch
|
||||
### 2. Safety Checks
|
||||
|
||||
2. **Review Changes**
|
||||
- Run `git diff --stat` to see change statistics
|
||||
- Confirm all changes are intentional
|
||||
- Check for any uncommitted work
|
||||
|
||||
3. **Security Checks**
|
||||
- ❌ No secrets or credentials in changes
|
||||
- ❌ No API keys, passwords, or tokens
|
||||
- ❌ No `.env` files or private keys
|
||||
- ✅ `.gitignore` properly configured
|
||||
- ✅ No large binary files without Git LFS
|
||||
- ✅ No build artifacts (node_modules, dist, __pycache__)
|
||||
|
||||
## Workflow Steps
|
||||
|
||||
### Step 1: Show Current Status
|
||||
|
||||
Run `git status` and display:
|
||||
- Modified files
|
||||
- Added files
|
||||
- Deleted files
|
||||
- Untracked files
|
||||
|
||||
### Step 2: Show Change Statistics
|
||||
|
||||
Run `git diff --stat` to show:
|
||||
- Number of files changed
|
||||
- Total insertions
|
||||
- Total deletions
|
||||
|
||||
### Step 3: Safety Verification
|
||||
|
||||
⚠️ **STOP if any of these are detected:**
|
||||
**❌ STOP and WARN if detected:**
|
||||
- Secrets: `.env*`, `*.key`, `*.pem`, `credentials.json`, `secrets.yaml`, `id_rsa`, `*.p12`, `*.pfx`, `*.cer`
|
||||
- API Keys: Any `*_API_KEY`, `*_SECRET`, `*_TOKEN` variables with real values (not placeholders like `your-api-key`, `xxx`, `placeholder`)
|
||||
- Large files: `>10MB` without Git LFS
|
||||
- Build artifacts: `node_modules/`, `dist/`, `build/`, `__pycache__/`, `*.pyc`, `.venv/`
|
||||
- Temp files: `.DS_Store`, `thumbs.db`, `*.swp`, `*.tmp`
|
||||
|
||||
**API Key Validation:**
|
||||
Check modified files for patterns like:
|
||||
```bash
|
||||
# Sensitive files:
|
||||
.env
|
||||
.env.local
|
||||
*.key
|
||||
*.pem
|
||||
credentials.json
|
||||
secrets.yaml
|
||||
config/database.yml (with passwords)
|
||||
*.p12
|
||||
*.pfx
|
||||
id_rsa
|
||||
*.cer
|
||||
OPENAI_API_KEY=sk-proj-xxxxx # ❌ Real key detected!
|
||||
AWS_SECRET_KEY=AKIA... # ❌ Real key detected!
|
||||
STRIPE_API_KEY=sk_live_... # ❌ Real key detected!
|
||||
|
||||
# Large files (>10MB)
|
||||
*.mp4, *.mov, *.zip, *.tar.gz
|
||||
|
||||
# Build artifacts:
|
||||
node_modules/
|
||||
dist/
|
||||
build/
|
||||
__pycache__/
|
||||
*.pyc
|
||||
.DS_Store
|
||||
thumbs.db
|
||||
*.swp
|
||||
# ✅ Acceptable placeholders:
|
||||
API_KEY=your-api-key-here
|
||||
SECRET_KEY=placeholder
|
||||
TOKEN=xxx
|
||||
API_KEY=<your-key>
|
||||
SECRET=${YOUR_SECRET}
|
||||
```
|
||||
|
||||
If any detected, **WARN USER** and ask for confirmation.
|
||||
**✅ Verify:**
|
||||
- `.gitignore` properly configured
|
||||
- No merge conflicts
|
||||
- Correct branch (warn if main/master)
|
||||
- API keys are placeholders only
|
||||
|
||||
### Step 4: Request Confirmation
|
||||
|
||||
Present summary and ask:
|
||||
### 3. Request Confirmation
|
||||
|
||||
Present summary:
|
||||
```
|
||||
📊 Changes Summary:
|
||||
- X files modified
|
||||
- Y files added
|
||||
- Z files deleted
|
||||
- X files modified, Y added, Z deleted
|
||||
- Total: +AAA insertions, -BBB deletions
|
||||
|
||||
⚠️ I will now:
|
||||
1. Stage all changes (git add .)
|
||||
2. Create a descriptive commit
|
||||
3. Push to remote repository
|
||||
🔒 Safety: ✅ No secrets | ✅ No large files | ⚠️ [warnings]
|
||||
🌿 Branch: [name] → origin/[name]
|
||||
|
||||
Current branch: [branch-name]
|
||||
Remote: [remote-url]
|
||||
|
||||
🔒 Safety checks:
|
||||
✅ No secrets detected
|
||||
✅ No large files
|
||||
✅ .gitignore configured
|
||||
⚠️ [Any warnings]
|
||||
I will: git add . → commit → push
|
||||
|
||||
Type 'yes' to proceed or 'no' to cancel.
|
||||
```
|
||||
|
||||
**WAIT for explicit user confirmation before proceeding.**
|
||||
**WAIT for explicit "yes" before proceeding.**
|
||||
|
||||
### Step 5: Stage All Changes (After Confirmation)
|
||||
### 4. Execute (After Confirmation)
|
||||
|
||||
Execute:
|
||||
Run sequentially:
|
||||
```bash
|
||||
git add .
|
||||
git status # Verify staging
|
||||
```
|
||||
|
||||
Verify staging:
|
||||
```bash
|
||||
git status
|
||||
```
|
||||
### 5. Generate Commit Message
|
||||
|
||||
### Step 6: Generate Commit Message
|
||||
|
||||
Analyze the changes and create a descriptive conventional commit message:
|
||||
Analyze changes and create conventional commit:
|
||||
|
||||
**Format:**
|
||||
```
|
||||
[type]: Brief summary (max 72 characters)
|
||||
|
||||
Detailed description of changes:
|
||||
- Key change 1
|
||||
- Key change 2
|
||||
- Key change 3
|
||||
```
|
||||
|
||||
**Commit Types:**
|
||||
- `feat`: New feature or enhancement
|
||||
- `fix`: Bug fix
|
||||
- `docs`: Documentation changes only
|
||||
- `style`: Code formatting, missing semicolons, etc.
|
||||
- `refactor`: Code restructuring without behavior change
|
||||
- `test`: Adding or updating tests
|
||||
- `chore`: Maintenance, dependencies, config
|
||||
- `perf`: Performance improvements
|
||||
- `build`: Build system or external dependencies
|
||||
- `ci`: CI/CD configuration changes
|
||||
**Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `build`, `ci`
|
||||
|
||||
**Examples:**
|
||||
**Example:**
|
||||
```
|
||||
feat: Add user authentication with JWT tokens
|
||||
docs: Update concept README files with comprehensive documentation
|
||||
|
||||
- Implement login and registration endpoints
|
||||
- Add JWT token generation and validation
|
||||
- Create authentication middleware
|
||||
- Add comprehensive auth tests
|
||||
```
|
||||
|
||||
```
|
||||
docs: Update all concept README files with comprehensive documentation
|
||||
|
||||
Extract and consolidate information from guide into individual folders
|
||||
- Add architecture diagrams and tables
|
||||
- Include practical examples
|
||||
- Expand best practices sections
|
||||
```
|
||||
|
||||
### Step 7: Create Commit
|
||||
### 6. Commit and Push
|
||||
|
||||
Execute:
|
||||
```bash
|
||||
git commit -m "$(cat <<'EOF'
|
||||
[Generated commit message]
|
||||
EOF
|
||||
)"
|
||||
git push # If fails: git pull --rebase && git push
|
||||
git log -1 --oneline --decorate # Verify
|
||||
```
|
||||
|
||||
Show commit hash and message.
|
||||
### 7. Confirm Success
|
||||
|
||||
### Step 8: Push to Remote
|
||||
|
||||
Execute:
|
||||
```bash
|
||||
git push
|
||||
```
|
||||
|
||||
If push fails, try:
|
||||
```bash
|
||||
git pull --rebase origin [branch-name]
|
||||
git push
|
||||
```
|
||||
|
||||
### Step 9: Verify Success
|
||||
|
||||
Show:
|
||||
```bash
|
||||
git log -1 --oneline --decorate
|
||||
```
|
||||
|
||||
Confirm:
|
||||
```
|
||||
✅ Successfully pushed to remote!
|
||||
|
||||
Commit: [hash] [message]
|
||||
Branch: [branch] → origin/[branch]
|
||||
Files changed: X
|
||||
```
|
||||
|
||||
## Safety Guidelines
|
||||
|
||||
### ❌ DO NOT Proceed If:
|
||||
|
||||
- **Secrets detected**: API keys, passwords, tokens, certificates
|
||||
- **Sensitive data**: Database dumps, user data, PII
|
||||
- **Large files**: Files >10MB without Git LFS
|
||||
- **Build artifacts**: node_modules, dist, __pycache__, .venv
|
||||
- **Temporary files**: .DS_Store, *.swp, *.tmp, thumbs.db
|
||||
- **User hasn't confirmed**: Always wait for explicit "yes"
|
||||
- **Protected branch**: main/master without proper review process
|
||||
- **Merge conflicts**: Unresolved conflicts exist
|
||||
- **Failing tests**: Pre-commit hooks or CI failing
|
||||
|
||||
### ✅ Good Use Cases:
|
||||
|
||||
- Documentation updates across multiple files
|
||||
- Feature implementation with tests and docs
|
||||
- Bug fixes with related test updates
|
||||
- Configuration and setup changes
|
||||
- Refactoring with comprehensive changes
|
||||
- Project-wide formatting or linting fixes
|
||||
- End-of-day commit of working feature
|
||||
|
||||
### ⚠️ Warning Signs - Ask User First:
|
||||
|
||||
```
|
||||
Modified: .env
|
||||
Modified: config/secrets.yml
|
||||
Added: private_key.pem
|
||||
Added: node_modules/ (1,234 files)
|
||||
Warning: Large file detected: video.mp4 (45MB)
|
||||
Warning: On protected branch: main
|
||||
Warning: Pre-commit hook failed
|
||||
Files changed: X (+insertions, -deletions)
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### If `git add .` fails:
|
||||
1. Check file permissions
|
||||
2. Look for locked files
|
||||
3. Verify repository is initialized
|
||||
4. Run `git status` for diagnostics
|
||||
- **git add fails**: Check permissions, locked files, verify repo initialized
|
||||
- **git commit fails**: Fix pre-commit hooks, check git config (user.name/email)
|
||||
- **git push fails**:
|
||||
- Non-fast-forward: `git pull --rebase && git push`
|
||||
- No remote branch: `git push -u origin [branch]`
|
||||
- Protected branch: Use PR workflow instead
|
||||
|
||||
### If `git commit` fails:
|
||||
1. **Pre-commit hooks failed**: Fix issues and retry
|
||||
2. **No changes to commit**: Already up to date
|
||||
3. **Invalid commit message**: Adjust format
|
||||
4. **Git config missing**: Set user.name and user.email
|
||||
## When to Use
|
||||
|
||||
### If `git push` fails:
|
||||
1. **Rejected (non-fast-forward)**:
|
||||
```bash
|
||||
git pull --rebase
|
||||
git push
|
||||
```
|
||||
✅ **Good:**
|
||||
- Multi-file documentation updates
|
||||
- Feature with tests and docs
|
||||
- Bug fixes across files
|
||||
- Project-wide formatting/refactoring
|
||||
- Configuration changes
|
||||
|
||||
2. **Permission denied**: Check credentials and access
|
||||
❌ **Avoid:**
|
||||
- Uncertain what's being committed
|
||||
- Contains secrets/sensitive data
|
||||
- Protected branches without review
|
||||
- Merge conflicts present
|
||||
- Want granular commit history
|
||||
- Pre-commit hooks failing
|
||||
|
||||
3. **Remote branch doesn't exist**:
|
||||
```bash
|
||||
git push -u origin [branch-name]
|
||||
```
|
||||
## Alternatives
|
||||
|
||||
4. **Protected branch**: Use pull request workflow
|
||||
If user wants control, suggest:
|
||||
1. **Selective staging**: Review/stage specific files
|
||||
2. **Interactive staging**: `git add -p` for patch selection
|
||||
3. **PR workflow**: Create branch → push → PR (use `/pr` command)
|
||||
|
||||
## Alternative Workflows
|
||||
|
||||
If user wants more control, suggest:
|
||||
|
||||
**Option 1: Selective Staging**
|
||||
```
|
||||
Would you like to:
|
||||
1. Select specific files to commit?
|
||||
2. Review each file individually?
|
||||
3. Create multiple commits by category?
|
||||
```
|
||||
|
||||
**Option 2: Interactive Staging**
|
||||
```
|
||||
Use `git add -p` for interactive patch selection?
|
||||
This lets you review each change before staging.
|
||||
```
|
||||
|
||||
**Option 3: Pull Request Flow**
|
||||
```
|
||||
Instead of direct push, would you like to:
|
||||
1. Create a feature branch
|
||||
2. Push to branch
|
||||
3. Create pull request
|
||||
Use the /pr command for this workflow.
|
||||
```
|
||||
|
||||
## Post-Push Actions
|
||||
|
||||
After successful push:
|
||||
|
||||
### 1. Verify on Remote
|
||||
- Check GitHub/GitLab/Bitbucket web interface
|
||||
- Confirm commit appears correctly
|
||||
- Review diff on remote
|
||||
|
||||
### 2. CI/CD Pipeline (if applicable)
|
||||
- Confirm pipeline started
|
||||
- Monitor build status
|
||||
- Check for any failures
|
||||
|
||||
### 3. Team Notification (if applicable)
|
||||
- Notify in Slack/Teams channel
|
||||
- Update issue tracker (close/link issues)
|
||||
- Tag reviewers for PR
|
||||
|
||||
### 4. Local Cleanup
|
||||
```bash
|
||||
# Verify everything is clean
|
||||
git status
|
||||
|
||||
# Should show:
|
||||
# On branch [name]
|
||||
# Your branch is up to date with 'origin/[name]'.
|
||||
# nothing to commit, working tree clean
|
||||
```
|
||||
|
||||
## Example Interaction
|
||||
|
||||
**User**: `/push-all`
|
||||
|
||||
**Assistant**:
|
||||
```
|
||||
🔍 Analyzing repository status...
|
||||
|
||||
📊 Current Status:
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Modified files (9):
|
||||
✏️ 01-slash-commands/README.md
|
||||
✏️ 02-subagents/README.md
|
||||
✏️ 03-memory/README.md
|
||||
✏️ 04-mcp/README.md
|
||||
✏️ 05-skills/README.md
|
||||
✏️ 06-plugins/README.md
|
||||
✏️ 07-hooks/README.md
|
||||
✏️ 08-checkpoints/README.md
|
||||
✏️ 09-advanced-features/README.md
|
||||
|
||||
📈 Change Statistics:
|
||||
9 files changed
|
||||
+3,706 insertions
|
||||
-587 deletions
|
||||
|
||||
🔒 Safety Checks:
|
||||
✅ No secrets detected
|
||||
✅ No large files (>10MB)
|
||||
✅ .gitignore properly configured
|
||||
✅ No build artifacts
|
||||
✅ No temporary files
|
||||
|
||||
🌿 Branch Information:
|
||||
Current: main
|
||||
Remote: origin/main
|
||||
Status: Up to date (can fast-forward)
|
||||
|
||||
📝 Proposed commit message:
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
docs: Update all concept README files with comprehensive documentation
|
||||
|
||||
Extract and consolidate information from guide into individual folders:
|
||||
- Add architecture diagrams, tables, and flowcharts
|
||||
- Include practical code examples and templates
|
||||
- Expand best practices and troubleshooting sections
|
||||
- Provide installation instructions for all concepts
|
||||
|
||||
Total: +3,706 lines of comprehensive documentation
|
||||
|
||||
🤖 Generated with Claude Code
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
⚠️ I will now:
|
||||
1. Stage all changes (git add .)
|
||||
2. Commit with the message above
|
||||
3. Push to origin/main
|
||||
|
||||
⚠️ This affects 9 files. Please confirm.
|
||||
|
||||
Type 'yes' to proceed, 'no' to cancel, or 'review' to see diffs.
|
||||
```
|
||||
|
||||
**User**: `yes`
|
||||
|
||||
**Assistant**:
|
||||
```
|
||||
✅ Staging all changes...
|
||||
git add .
|
||||
|
||||
✅ Creating commit...
|
||||
git commit -m "docs: Update all concept README files..."
|
||||
|
||||
✅ Pushing to remote...
|
||||
git push origin main
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
🎉 Successfully pushed to remote!
|
||||
|
||||
Commit: 41527ae docs: Update all concept README files...
|
||||
Branch: main → origin/main
|
||||
Files: 9 changed (+3,706, -587)
|
||||
Remote: https://github.com/user/repo
|
||||
|
||||
✅ All changes have been successfully pushed!
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
## Quick Reference Card
|
||||
|
||||
**What this command does:**
|
||||
1. ✅ Checks git status and shows changes
|
||||
2. ✅ Displays change statistics
|
||||
3. ✅ Performs comprehensive safety checks
|
||||
4. ⚠️ Requests explicit user confirmation
|
||||
5. ✅ Stages all changes with `git add .`
|
||||
6. ✅ Generates descriptive conventional commit
|
||||
7. ✅ Creates commit with proper message
|
||||
8. ✅ Pushes to remote repository
|
||||
9. ✅ Verifies and confirms success
|
||||
|
||||
**When to use:**
|
||||
- ✅ Coordinated multi-file documentation updates
|
||||
- ✅ Feature implementation with tests and docs
|
||||
- ✅ Bug fixes affecting multiple files
|
||||
- ✅ Project-wide refactoring or formatting
|
||||
- ✅ End-of-day commits of working features
|
||||
- ✅ Configuration and setup changes
|
||||
|
||||
**When NOT to use:**
|
||||
- ❌ Uncertain about what's being committed
|
||||
- ❌ Contains sensitive data or secrets
|
||||
- ❌ On protected branches (main/master) without review
|
||||
- ❌ Merge conflicts are present
|
||||
- ❌ Want granular commit history for different changes
|
||||
- ❌ Pre-commit hooks are failing
|
||||
- ❌ Want to review each change individually
|
||||
|
||||
## Related Commands
|
||||
|
||||
- **`/pr`** - Full pull request preparation with checklist
|
||||
- **`/optimize`** - Code optimization before committing
|
||||
- **Individual git commands** - For more granular control
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use descriptive branch names**: `feature/auth`, `fix/login-bug`
|
||||
2. **Commit related changes together**: Don't mix features and fixes
|
||||
3. **Review before pushing**: Always check `git diff`
|
||||
4. **Pull before push**: Avoid conflicts with `git pull --rebase`
|
||||
5. **Use conventional commits**: Helps with changelog generation
|
||||
6. **Test before commit**: Run tests to catch issues early
|
||||
7. **Keep commits atomic**: One logical change per commit when possible
|
||||
8. **Write clear messages**: Future you will thank present you
|
||||
|
||||
---
|
||||
|
||||
**⚠️ Remember**: With great automation comes great responsibility. Always review your changes before pushing! When in doubt, use individual git commands for more control.
|
||||
**⚠️ Remember**: Always review changes before pushing. When in doubt, use individual git commands for more control.
|
||||
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
name: Setup CI/CD Pipeline
|
||||
description: Implement pre-commit hooks and GitHub Actions for quality assurance
|
||||
tags: ci-cd, devops, automation
|
||||
---
|
||||
|
||||
# Setup CI/CD Pipeline
|
||||
|
||||
Implement comprehensive DevOps quality gates adapted to project type:
|
||||
|
||||
1. **Analyze project**: Detect language(s), framework, build system, and existing tooling
|
||||
2. **Configure pre-commit hooks** with language-specific tools:
|
||||
- Formatting: Prettier/Black/gofmt/rustfmt/etc.
|
||||
- Linting: ESLint/Ruff/golangci-lint/Clippy/etc.
|
||||
- Security: Bandit/gosec/cargo-audit/npm audit/etc.
|
||||
- Type checking: TypeScript/mypy/flow (if applicable)
|
||||
- Tests: Run relevant test suites
|
||||
3. **Create GitHub Actions workflows** (.github/workflows/):
|
||||
- Mirror pre-commit checks on push/PR
|
||||
- Multi-version/platform matrix (if applicable)
|
||||
- Build and test verification
|
||||
- Deployment steps (if needed)
|
||||
4. **Verify pipeline**: Test locally, create test PR, confirm all checks pass
|
||||
|
||||
Use free/open-source tools. Respect existing configs. Keep execution fast.
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
name: Expand Unit Tests
|
||||
description: Increase test coverage by targeting untested branches and edge cases
|
||||
tags: testing, coverage, unit-tests
|
||||
---
|
||||
|
||||
# Expand Unit Tests
|
||||
|
||||
Expand existing unit tests adapted to project's testing framework:
|
||||
|
||||
1. **Analyze coverage**: Run coverage report to identify untested branches, edge cases, and low-coverage areas
|
||||
2. **Identify gaps**: Review code for logical branches, error paths, boundary conditions, null/empty inputs
|
||||
3. **Write tests** using project's framework:
|
||||
- Jest/Vitest/Mocha (JavaScript/TypeScript)
|
||||
- pytest/unittest (Python)
|
||||
- Go testing/testify (Go)
|
||||
- Rust test framework (Rust)
|
||||
4. **Target specific scenarios**:
|
||||
- Error handling and exceptions
|
||||
- Boundary values (min/max, empty, null)
|
||||
- Edge cases and corner cases
|
||||
- State transitions and side effects
|
||||
5. **Verify improvement**: Run coverage again, confirm measurable increase
|
||||
|
||||
Present new test code blocks only. Follow existing test patterns and naming conventions.
|
||||
@@ -0,0 +1,18 @@
|
||||
<!-- OPENSPEC:START -->
|
||||
# OpenSpec Instructions
|
||||
|
||||
These instructions are for AI assistants working in this project.
|
||||
|
||||
Always open `@/openspec/AGENTS.md` when the request:
|
||||
- Mentions planning or proposals (words like proposal, spec, change, plan)
|
||||
- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
|
||||
- Sounds ambiguous and you need the authoritative spec before coding
|
||||
|
||||
Use `@/openspec/AGENTS.md` to learn:
|
||||
- How to create and apply change proposals
|
||||
- Spec format and conventions
|
||||
- Project structure and guidelines
|
||||
|
||||
Keep this managed block so 'openspec update' can refresh the instructions.
|
||||
|
||||
<!-- OPENSPEC:END -->
|
||||
@@ -0,0 +1,18 @@
|
||||
<!-- OPENSPEC:START -->
|
||||
# OpenSpec Instructions
|
||||
|
||||
These instructions are for AI assistants working in this project.
|
||||
|
||||
Always open `@/openspec/AGENTS.md` when the request:
|
||||
- Mentions planning or proposals (words like proposal, spec, change, plan)
|
||||
- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
|
||||
- Sounds ambiguous and you need the authoritative spec before coding
|
||||
|
||||
Use `@/openspec/AGENTS.md` to learn:
|
||||
- How to create and apply change proposals
|
||||
- Spec format and conventions
|
||||
- Project structure and guidelines
|
||||
|
||||
Keep this managed block so 'openspec update' can refresh the instructions.
|
||||
|
||||
<!-- OPENSPEC:END -->
|
||||
|
||||
@@ -26,6 +26,7 @@ Complete collection of examples for some important Claude Code features and conc
|
||||
| **Checkpoints** | Session snapshots & rewind | [08-checkpoints/](08-checkpoints/) |
|
||||
| **Advanced Features** | Planning, thinking, background tasks | [09-advanced-features/](09-advanced-features/) |
|
||||
| **CLI Reference** | Commands, flags, and options | [10-cli/](10-cli/) |
|
||||
| **Blog Posts** | Real-world usage examples | [blog-post/](blog-post/) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -0,0 +1,328 @@
|
||||
# 4 Essential Slash Commands I Use in Every Project
|
||||
|
||||
*Building on the foundation of [Discovering Claude Code Slash Commands](https://medium.com/@luongnv89/discovering-claude-code-slash-commands-cdc17f0dfb29), this post focuses on the practical workflow commands I've found most valuable across different development phases.*
|
||||
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
After mastering the basics of Claude Code slash commands, I discovered that certain commands became indispensable across every project. These four commands form a complete development workflow—from quick commits to comprehensive project infrastructure.
|
||||
|
||||
In this post, I'll share how I integrate these commands into my development lifecycle, when to use each one, and practical tips for getting the most value from them.
|
||||
|
||||
---
|
||||
|
||||
## Development Workflow Overview
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[POC Phase] --> B[/push-all - Quick commits\]
|
||||
B --> C[MVP Complete]
|
||||
C --> D[/setup-ci-cd - Quality gates\]
|
||||
D --> E[Development Milestones]
|
||||
E --> F[/unit-test-expand - Test coverage\]
|
||||
F --> G[Project Polish]
|
||||
G --> H[/doc-refactor - Documentation\]
|
||||
H --> I[Production Ready]
|
||||
|
||||
style B fill:#e1f5fe
|
||||
style D fill:#f3e5f5
|
||||
style F fill:#e8f5e8
|
||||
style H fill:#fff3e0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. `/push-all` - When You Need to Push Changes
|
||||
|
||||
**Best for**: Quick deployment of coherent changesets
|
||||
**When to use**: Multiple related changes that belong together
|
||||
**Project phase**: Any phase, especially POC and rapid iteration
|
||||
|
||||
### Why I Use It
|
||||
|
||||
The `/push-all` command has become my go-to for situations where I've made multiple interconnected changes that need to be committed together. Unlike manual git workflows, this command provides comprehensive safety checks that prevent me from accidentally committing sensitive information.
|
||||
|
||||
### Key Features
|
||||
|
||||
- **Safety First**: Automatically scans for secrets, API keys, and large files
|
||||
- **Smart Commit Messages**: Generates conventional commit messages based on changes
|
||||
- **Confirmation Required**: Presents a clear summary before executing
|
||||
- **Error Recovery**: Handles common git issues automatically
|
||||
|
||||
### When to Use `/push-all`
|
||||
|
||||
✅ **Perfect for:**
|
||||
- Multi-file documentation updates
|
||||
- Feature implementations with tests and docs
|
||||
- Bug fixes across multiple files
|
||||
- Project-wide formatting/refactoring
|
||||
- Configuration changes
|
||||
|
||||
❌ **Avoid when:**
|
||||
- You're uncertain what's being committed
|
||||
- Contains sensitive data
|
||||
- Working on protected branches
|
||||
- You want granular commit history
|
||||
|
||||
### Full Command Reference
|
||||
|
||||
Since this command exceeds 30 lines (153 lines total), you can view the complete implementation here:
|
||||
|
||||
**[📄 View complete `/push-all` command](../01-slash-commands/push-all.md)**
|
||||
|
||||
---
|
||||
|
||||
## 2. `/setup-ci-cd` - After POC Completion
|
||||
|
||||
**Best for**: Establishing quality infrastructure
|
||||
**When to use**: After completing POC, before scaling development
|
||||
**Project phase**: POC → MVP transition
|
||||
|
||||
### Why I Use It
|
||||
|
||||
Once my POC is working and I'm ready to build a proper project, `/setup-ci-cd` ensures I have the right quality gates in place. It adapts to my project's tech stack and sets up both pre-commit hooks and GitHub Actions without me having to research best practices for each language.
|
||||
|
||||
### Command Content
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: Setup CI/CD Pipeline
|
||||
description: Implement pre-commit hooks and GitHub Actions for quality assurance
|
||||
tags: ci-cd, devops, automation
|
||||
---
|
||||
|
||||
# Setup CI/CD Pipeline
|
||||
|
||||
Implement comprehensive DevOps quality gates adapted to project type:
|
||||
|
||||
1. **Analyze project**: Detect language(s), framework, build system, and existing tooling
|
||||
2. **Configure pre-commit hooks** with language-specific tools:
|
||||
- Formatting: Prettier/Black/gofmt/rustfmt/etc.
|
||||
- Linting: ESLint/Ruff/golangci-lint/Clippy/etc.
|
||||
- Security: Bandit/gosec/cargo-audit/npm audit/etc.
|
||||
- Type checking: TypeScript/mypy/flow (if applicable)
|
||||
- Tests: Run relevant test suites
|
||||
3. **Create GitHub Actions workflows** (.github/workflows/):
|
||||
- Mirror pre-commit checks on push/PR
|
||||
- Multi-version/platform matrix (if applicable)
|
||||
- Build and test verification
|
||||
- Deployment steps (if needed)
|
||||
4. **Verify pipeline**: Test locally, create test PR, confirm all checks pass
|
||||
|
||||
Use free/open-source tools. Respect existing configs. Keep execution fast.
|
||||
```
|
||||
|
||||
### What It Sets Up
|
||||
|
||||
- **Pre-commit hooks**: Local quality checks before each commit
|
||||
- **GitHub Actions**: CI/CD pipeline for pull requests and pushes
|
||||
- **Language-specific tools**: Automatically detects and configures the right tools
|
||||
- **Security scanning**: Integrates security best practices
|
||||
- **Multi-platform support**: Configures testing across different environments
|
||||
|
||||
---
|
||||
|
||||
## 3. `/doc-refactor` - After MVP Completion
|
||||
|
||||
**Best for**: Project documentation organization
|
||||
**When to use**: After MVP is functional, before scaling team
|
||||
**Project phase**: MVP → Production preparation
|
||||
|
||||
### Why I Use It
|
||||
|
||||
Documentation often becomes an afterthought during MVP development. `/doc-refactor` helps me reorganize scattered documentation into a coherent structure that scales with the team and project.
|
||||
|
||||
### Command Content
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: Documentation Refactor
|
||||
description: Restructure project documentation for clarity and accessibility
|
||||
tags: documentation, refactoring, organization
|
||||
---
|
||||
|
||||
# Documentation Refactor
|
||||
|
||||
Refactor project documentation structure adapted to project type:
|
||||
|
||||
1. **Analyze project**: Identify type (library/API/web app/CLI/microservices), architecture, and user personas
|
||||
2. **Centralize docs**: Move technical documentation to `docs/` with proper cross-references
|
||||
3. **Root README.md**: Streamline as entry point with overview, quickstart, modules/components summary, license, contacts
|
||||
4. **Component docs**: Add module/package/service-level README files with setup and testing instructions
|
||||
5. **Organize `docs/`** by relevant categories:
|
||||
- Architecture, API Reference, Database, Design, Troubleshooting, Deployment, Contributing (adapt to project needs)
|
||||
6. **Create guides** (select applicable):
|
||||
- User Guide: End-user documentation for applications
|
||||
- API Documentation: Endpoints, authentication, examples for APIs
|
||||
- Development Guide: Setup, testing, contribution workflow
|
||||
- Deployment Guide: Production deployment for services/apps
|
||||
7. **Use Mermaid** for all diagrams (architecture, flows, schemas)
|
||||
|
||||
Keep docs concise, scannable, and contextual to project type.
|
||||
```
|
||||
|
||||
### Documentation Structure It Creates
|
||||
|
||||
```
|
||||
project/
|
||||
├── README.md (streamlined entry point)
|
||||
├── docs/
|
||||
│ ├── architecture/
|
||||
│ ├── api-reference/
|
||||
│ ├── user-guide/
|
||||
│ ├── development-guide/
|
||||
│ └── deployment/
|
||||
└── src/
|
||||
└── [component]/README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. `/unit-test-expand` - After Each Milestone
|
||||
|
||||
**Best for**: Systematic test coverage improvement
|
||||
**When to use**: After completing development milestones
|
||||
**Project phase**: Throughout development, at milestone checkpoints
|
||||
|
||||
### Why I Use It
|
||||
|
||||
Instead of letting test coverage lag behind, I use `/unit-test-expand` at each milestone to systematically identify and fill testing gaps. It's particularly valuable for catching edge cases and error paths that manual testing often misses.
|
||||
|
||||
### Command Content
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: Expand Unit Tests
|
||||
description: Increase test coverage by targeting untested branches and edge cases
|
||||
tags: testing, coverage, unit-tests
|
||||
---
|
||||
|
||||
# Expand Unit Tests
|
||||
|
||||
Expand existing unit tests adapted to project's testing framework:
|
||||
|
||||
1. **Analyze coverage**: Run coverage report to identify untested branches, edge cases, and low-coverage areas
|
||||
2. **Identify gaps**: Review code for logical branches, error paths, boundary conditions, null/empty inputs
|
||||
3. **Write tests** using project's framework:
|
||||
- Jest/Vitest/Mocha (JavaScript/TypeScript)
|
||||
- pytest/unittest (Python)
|
||||
- Go testing/testify (Go)
|
||||
- Rust test framework (Rust)
|
||||
4. **Target specific scenarios**:
|
||||
- Error handling and exceptions
|
||||
- Boundary values (min/max, empty, null)
|
||||
- Edge cases and corner cases
|
||||
- State transitions and side effects
|
||||
5. **Verify improvement**: Run coverage again, confirm measurable increase
|
||||
|
||||
Present new test code blocks only. Follow existing test patterns and naming conventions.
|
||||
```
|
||||
|
||||
### Testing Gaps It Targets
|
||||
|
||||
- **Error paths**: Exception handling and failure scenarios
|
||||
- **Boundary conditions**: Edge values at limits and empty states
|
||||
- **State transitions**: Side effects and state changes
|
||||
- **Integration points**: Cross-component interactions
|
||||
- **Security scenarios**: Input validation and authorization
|
||||
|
||||
---
|
||||
|
||||
## Integration Into Development Lifecycle
|
||||
|
||||
### Phase-Based Usage
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[POC] --> B[push-all]
|
||||
B --> C[MVP]
|
||||
C --> D[setup-ci-cd]
|
||||
D --> E[Development]
|
||||
E --> F[unit-test-expand]
|
||||
F --> G[Polish]
|
||||
G --> H[doc-refactor]
|
||||
H --> I[Production]
|
||||
|
||||
subgraph "Quick Iteration"
|
||||
B
|
||||
end
|
||||
|
||||
subgraph "Foundation"
|
||||
D
|
||||
end
|
||||
|
||||
subgraph "Quality Gates"
|
||||
F
|
||||
end
|
||||
|
||||
subgraph "Documentation"
|
||||
H
|
||||
end
|
||||
```
|
||||
|
||||
### My Typical Workflow
|
||||
|
||||
1. **POC Phase**: Use `/push-all` frequently for rapid iteration
|
||||
2. **MVP Complete**: Run `/setup-ci-cd` to establish quality infrastructure
|
||||
3. **Development Sprints**: Use `/unit-test-expand` at each milestone
|
||||
4. **Pre-Production**: Execute `/doc-refactor` for project documentation
|
||||
5. **Ongoing**: `/push-all` continues to serve for coherent changesets
|
||||
|
||||
---
|
||||
|
||||
## Tips for Maximum Value
|
||||
|
||||
### 1. Customize Commands for Your Project
|
||||
|
||||
While these commands work out-of-the-box, I often customize them for project-specific needs:
|
||||
|
||||
```bash
|
||||
# Add project-specific patterns to push-all safety checks
|
||||
# Customize doc-refactor for your documentation standards
|
||||
# Extend unit-test-expand with your testing framework preferences
|
||||
```
|
||||
|
||||
### 2. Team Adoption
|
||||
|
||||
- **Start with `/push-all`**: Easiest to adopt and provides immediate value
|
||||
- **Progressive introduction**: Add commands as the project matures
|
||||
- **Document customizations**: Keep track of project-specific modifications
|
||||
|
||||
### 3. Integration with Existing Workflows
|
||||
|
||||
These commands complement rather than replace existing practices:
|
||||
|
||||
- **Git hooks**: Can trigger these commands automatically
|
||||
- **CI/CD pipelines**: Use them as templates for pipeline steps
|
||||
- **Code reviews**: Reference command outputs in review discussions
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
These four slash commands have transformed how I approach project development:
|
||||
|
||||
- **`/push-all`** provides safety and speed for coherent changes
|
||||
- **`/setup-ci-cd`** establishes quality foundations without research overhead
|
||||
- **`/unit-test-expand`** ensures systematic test coverage improvement
|
||||
- **`/doc-refactor`** creates scalable documentation structures
|
||||
|
||||
Together, they form a complete workflow that adapts to different project phases while maintaining consistency and quality standards.
|
||||
|
||||
The real power comes from integrating them into your natural development rhythm—not as additional overhead, but as tools that make each phase more efficient and reliable.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Try `/push-all`** on your next multi-file change
|
||||
2. **Run `/setup-ci-cd`** after your next POC completion
|
||||
3. **Use `/unit-test-expand`** at your next milestone
|
||||
4. **Execute `/doc-refactor`** before your next team expansion
|
||||
|
||||
Have questions or want to share your own essential slash commands? [Join the discussion](https://github.com/luongnv89/claude-howto/issues) in the claude-howto repository.
|
||||
|
||||
---
|
||||
|
||||
*This post is part of the [claude-howto](../) project, which provides comprehensive examples and documentation for Claude Code features.*
|
||||
@@ -0,0 +1,163 @@
|
||||
# Design: Context Usage Tracking via Hook Pairs
|
||||
|
||||
## Context
|
||||
|
||||
Users need visibility into token consumption during Claude Code sessions. While Claude Code provides internal context management, users lack tools to:
|
||||
- Track token usage per request
|
||||
- Monitor cumulative context growth
|
||||
- Understand when they're approaching context limits
|
||||
|
||||
The existing `Stop` hook example provides cumulative usage but not per-request deltas.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
### Goals
|
||||
- Document a reliable method to track per-request token consumption
|
||||
- Provide a working example users can copy and modify
|
||||
- Explain the methodology and its limitations clearly
|
||||
- Use existing hook events (`UserPromptSubmit`, `Stop`) without requiring new capabilities
|
||||
|
||||
### Non-Goals
|
||||
- Implement actual token counting (we use character-based estimation)
|
||||
- Access internal Claude Code context metrics
|
||||
- Modify Claude Code's behavior or internal state
|
||||
- Track system prompt tokens (not in transcript)
|
||||
|
||||
## Decisions
|
||||
|
||||
### Decision 1: Use UserPromptSubmit + Stop Hook Pair
|
||||
**What**: Use `UserPromptSubmit` as the "pre-message" hook and `Stop` as the "post-response" hook.
|
||||
|
||||
**Why**: These are the natural lifecycle points:
|
||||
- `UserPromptSubmit` fires before the prompt is sent to the model
|
||||
- `Stop` fires after Claude completes its response
|
||||
|
||||
**Alternatives Considered**:
|
||||
| Option | Pros | Cons |
|
||||
|--------|------|------|
|
||||
| SessionStart + Stop | Captures full session | No per-request granularity |
|
||||
| PreToolUse + PostToolUse | Captures tool overhead | Missing prompt/response tokens |
|
||||
| UserPromptSubmit + Stop | Natural request boundaries | Requires temp file for state |
|
||||
|
||||
### Decision 2: Use Temp File for State Persistence
|
||||
**What**: Store pre-message token count in a temp file keyed by session ID.
|
||||
|
||||
**Why**: Hooks are stateless processes; we need persistence between the two hook invocations.
|
||||
|
||||
**Implementation**:
|
||||
```python
|
||||
import tempfile
|
||||
import os
|
||||
|
||||
def get_state_file(session_id: str) -> str:
|
||||
return os.path.join(tempfile.gettempdir(), f"claude-tokens-{session_id}.json")
|
||||
```
|
||||
|
||||
### Decision 3: Single Script with Mode Detection
|
||||
**What**: One Python script handles both hooks, detecting mode via `hook_event_name`.
|
||||
|
||||
**Why**:
|
||||
- Reduces file count and complexity
|
||||
- Ensures consistent token calculation logic
|
||||
- Easier for users to understand and modify
|
||||
|
||||
**Structure**:
|
||||
```python
|
||||
def main():
|
||||
data = json.load(sys.stdin)
|
||||
event = data.get("hook_event_name")
|
||||
|
||||
if event == "UserPromptSubmit":
|
||||
record_pre_message_count(data)
|
||||
elif event == "Stop":
|
||||
report_delta(data)
|
||||
```
|
||||
|
||||
### Decision 4: Two Offline Token Counting Methods (No API Key)
|
||||
**What**: Provide two offline methods - tiktoken-based and simple character estimation.
|
||||
|
||||
**Why**:
|
||||
- No API key should be required for context tracking hooks
|
||||
- Anthropic hasn't released an official offline tokenizer
|
||||
- Users have different dependency tolerance levels
|
||||
|
||||
#### Method A: tiktoken with p50k_base (Recommended)
|
||||
|
||||
```python
|
||||
import tiktoken
|
||||
|
||||
def count_tokens_tiktoken(text: str) -> int:
|
||||
enc = tiktoken.get_encoding("p50k_base")
|
||||
return len(enc.encode(text))
|
||||
```
|
||||
|
||||
**Characteristics**:
|
||||
- ~90-95% accuracy compared to Claude's actual tokenizer
|
||||
- Works completely offline
|
||||
- Requires `tiktoken` dependency
|
||||
- Fast execution (<10ms)
|
||||
|
||||
#### Method B: Character-Based Estimation (Zero Dependencies)
|
||||
|
||||
```python
|
||||
def count_tokens_estimate(text: str) -> int:
|
||||
return len(text) // 4
|
||||
```
|
||||
|
||||
**Characteristics**:
|
||||
- ~80-90% accuracy for English text
|
||||
- No dependencies at all
|
||||
- Sub-millisecond latency
|
||||
- Less accurate for code and non-English text
|
||||
|
||||
**Trade-off Matrix**:
|
||||
|
||||
| Factor | tiktoken | Estimation |
|
||||
|--------|----------|------------|
|
||||
| Accuracy | ~90-95% | ~80-90% |
|
||||
| Speed | <10ms | <1ms |
|
||||
| Dependencies | tiktoken | None |
|
||||
| Offline | Yes | Yes |
|
||||
|
||||
**Note**: Anthropic hasn't released their official tokenizer publicly. The `tiktoken` approach uses OpenAI's tokenizer with `p50k_base` encoding as a reasonable approximation since both use BPE (byte-pair encoding).
|
||||
|
||||
## Token Delta Calculation Flow
|
||||
|
||||
```
|
||||
UserPromptSubmit Stop
|
||||
| |
|
||||
v v
|
||||
Read transcript Read transcript
|
||||
| |
|
||||
v v
|
||||
Count characters Count characters
|
||||
| |
|
||||
v v
|
||||
Estimate tokens (T1) Estimate tokens (T2)
|
||||
| |
|
||||
v v
|
||||
Save T1 to temp file Calculate delta = T2 - T1
|
||||
|
|
||||
v
|
||||
Report: "Request used ~X tokens"
|
||||
```
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| Temp file not found (hook failures) | Graceful fallback to cumulative-only reporting |
|
||||
| Inaccurate token estimates | Clear documentation of limitations |
|
||||
| Race conditions (concurrent sessions) | Session ID in filename for isolation |
|
||||
| Temp file cleanup | Use system temp directory (auto-cleaned) |
|
||||
|
||||
## Example Output Format
|
||||
|
||||
```
|
||||
Context Usage: ~12,500 tokens used (~125,000 remaining)
|
||||
This request: ~850 tokens (+6.8% of total)
|
||||
```
|
||||
|
||||
## Open Questions
|
||||
|
||||
None - design is straightforward given existing hook capabilities.
|
||||
@@ -0,0 +1,100 @@
|
||||
# Change: Add Context Usage Tracking Documentation via Pre-Message and Post-Response Hooks
|
||||
|
||||
## Why
|
||||
|
||||
Users want to monitor token consumption per request and overall context usage throughout a Claude Code session. Currently, the hooks documentation shows a basic context-usage example using the Stop hook, but it doesn't demonstrate how to track **per-request** token consumption by comparing measurements at two points in time.
|
||||
|
||||
By documenting how to use `UserPromptSubmit` as a "pre-message" hook and `Stop` as a "post-response" hook, users can calculate the delta in token usage for each request, enabling accurate per-request consumption metrics.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **ADDED**: Documentation for using `UserPromptSubmit` and `Stop` hooks together for context tracking
|
||||
- **ADDED**: A new example demonstrating token delta calculation between pre-message and post-response
|
||||
- **MODIFIED**: Enhance the existing context usage reporting requirement with delta-based tracking approach
|
||||
- **ADDED**: Detailed explanation of token estimation methodology and its limitations
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected specs: `hooks-documentation`
|
||||
- Affected code: `06-hooks/README.md` (documentation updates)
|
||||
- No breaking changes - purely additive documentation
|
||||
|
||||
## Technical Analysis
|
||||
|
||||
### Current Hook Events Mapping
|
||||
|
||||
| Desired Hook | Claude Code Event | Trigger Point |
|
||||
|--------------|-------------------|---------------|
|
||||
| Pre-Message Hook | `UserPromptSubmit` | Before user prompt is processed by the model |
|
||||
| Post-Response Hook | `Stop` | After model completes its full response |
|
||||
|
||||
### Token Counting Methods (Offline, No API Key)
|
||||
|
||||
Since we need offline token counting without an API key, we offer **two local approaches**:
|
||||
|
||||
#### Method 1: tiktoken with p50k_base (More Accurate)
|
||||
|
||||
Use OpenAI's `tiktoken` library with the `p50k_base` encoding as an approximation for Claude's tokenizer:
|
||||
|
||||
```python
|
||||
import tiktoken
|
||||
|
||||
enc = tiktoken.get_encoding("p50k_base")
|
||||
tokens = enc.encode(text)
|
||||
token_count = len(tokens)
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- More accurate than character estimation (~90-95% accuracy)
|
||||
- Works completely offline
|
||||
- No API key required
|
||||
- Fast execution
|
||||
|
||||
**Cons:**
|
||||
- Requires `tiktoken` dependency (`pip install tiktoken`)
|
||||
- Not Claude's exact tokenizer (approximation)
|
||||
|
||||
#### Method 2: Character-Based Estimation (Simplest)
|
||||
|
||||
For zero-dependency estimation:
|
||||
|
||||
```python
|
||||
estimated_tokens = len(text) // 4
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- No dependencies at all
|
||||
- Works offline
|
||||
- Extremely fast
|
||||
|
||||
**Cons:**
|
||||
- Less accurate (~80-90% for English text)
|
||||
- Varies more with code and non-English text
|
||||
|
||||
### Token Delta Calculation Approach
|
||||
|
||||
1. **Pre-Message (UserPromptSubmit)**: Read transcript, count tokens (via tiktoken or estimation)
|
||||
2. **Post-Response (Stop)**: Read transcript again, calculate new total, compute delta
|
||||
|
||||
**Accuracy Evaluation:**
|
||||
|
||||
| Factor | tiktoken Method | Character Estimation |
|
||||
|--------|-----------------|---------------------|
|
||||
| Token accuracy | ~90-95% | ~80-90% |
|
||||
| Dependencies | tiktoken | None |
|
||||
| Speed | Fast (<10ms) | Very fast (<1ms) |
|
||||
| Offline | Yes | Yes |
|
||||
|
||||
### Limitations
|
||||
|
||||
- **No official offline Claude tokenizer exists** - Anthropic hasn't released their tokenizer publicly
|
||||
- System prompts and internal Claude Code context are NOT in the transcript
|
||||
- The delta includes: user prompt + Claude's response + any tool outputs
|
||||
- Both methods are approximations; actual API token counts may differ slightly
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. Should we persist the pre-message count to a file, or can we rely on the hook's transient state?
|
||||
- **Recommendation**: Use a simple temp file in the session directory for reliability
|
||||
2. Should the example be a single Python script handling both hooks, or two separate scripts?
|
||||
- **Recommendation**: Single script with mode detection based on `hook_event_name`
|
||||
@@ -0,0 +1,106 @@
|
||||
# hooks-documentation Spec Delta
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Pre-Message and Post-Response Hook Pairs Documentation
|
||||
The hooks lesson SHALL document how to use `UserPromptSubmit` and `Stop` hooks together for context/token usage tracking.
|
||||
|
||||
#### Scenario: Understanding hook event timing for context tracking
|
||||
- **WHEN** a user wants to track per-request token consumption
|
||||
- **THEN** they find documentation explaining that `UserPromptSubmit` fires before the prompt is processed (pre-message)
|
||||
- **AND** they find documentation explaining that `Stop` fires after Claude completes its response (post-response)
|
||||
- **AND** they understand how to calculate the delta between these two points
|
||||
|
||||
#### Scenario: Token delta calculation methodology
|
||||
- **WHEN** a user implements a context tracking hook pair
|
||||
- **THEN** they find documentation explaining how to:
|
||||
- Record token count at `UserPromptSubmit` time
|
||||
- Calculate new token count at `Stop` time
|
||||
- Compute the delta representing per-request consumption
|
||||
|
||||
### Requirement: Context Tracking Hook Pair Example
|
||||
The hooks lesson SHALL provide a working example script that tracks context usage using pre-message and post-response hooks.
|
||||
|
||||
#### Scenario: Single script handles both hook events
|
||||
- **WHEN** a user copies the context-tracker.py example
|
||||
- **THEN** the script detects the hook event type via `hook_event_name`
|
||||
- **AND** handles `UserPromptSubmit` by saving current token estimate to a temp file
|
||||
- **AND** handles `Stop` by loading the saved count, calculating delta, and reporting usage
|
||||
|
||||
#### Scenario: Complete configuration for hook pair
|
||||
- **WHEN** a user wants to configure both hooks
|
||||
- **THEN** they find a complete settings.json example showing:
|
||||
- `UserPromptSubmit` hook configuration pointing to the context tracker script
|
||||
- `Stop` hook configuration pointing to the same script
|
||||
- Both hooks using the same script for consistent token calculation
|
||||
|
||||
#### Scenario: Per-request usage reporting
|
||||
- **WHEN** the context tracking hooks execute
|
||||
- **THEN** the Stop hook outputs a report showing:
|
||||
- Total estimated tokens used in session
|
||||
- Tokens consumed by the current request (delta)
|
||||
- Remaining capacity estimate
|
||||
|
||||
### Requirement: Token Counting Methods Documentation
|
||||
The hooks lesson SHALL document two offline token counting methods that require no API key.
|
||||
|
||||
#### Scenario: tiktoken-based token counting documented
|
||||
- **WHEN** a user wants more accurate offline token counts
|
||||
- **THEN** they find documentation for using `tiktoken` with `p50k_base` encoding
|
||||
- **AND** they see a Python example using `tiktoken.get_encoding("p50k_base")`
|
||||
- **AND** they understand it provides ~90-95% accuracy compared to Claude's tokenizer
|
||||
- **AND** they learn it requires the `tiktoken` dependency
|
||||
|
||||
#### Scenario: Character estimation token counting documented
|
||||
- **WHEN** a user wants zero-dependency token estimation
|
||||
- **THEN** they find documentation for the ~4 characters per token estimation ratio
|
||||
- **AND** they understand this provides ~80-90% accuracy for English text
|
||||
- **AND** they learn it works with no external dependencies
|
||||
|
||||
#### Scenario: Method comparison provided
|
||||
- **WHEN** a user needs to choose between token counting methods
|
||||
- **THEN** they find a comparison showing:
|
||||
- tiktoken method: ~90-95% accuracy, requires tiktoken, <10ms latency
|
||||
- Estimation method: ~80-90% accuracy, no dependencies, <1ms latency
|
||||
- **AND** both methods work completely offline without API keys
|
||||
|
||||
#### Scenario: Transcript contents explained
|
||||
- **WHEN** a user wants to understand what's included in token counts
|
||||
- **THEN** they find documentation explaining that the transcript includes:
|
||||
- User prompts
|
||||
- Claude's responses
|
||||
- Tool inputs and outputs
|
||||
- **AND** they understand that system prompts and internal context are NOT included
|
||||
|
||||
#### Scenario: No official Claude tokenizer caveat
|
||||
- **WHEN** a user reads about token counting accuracy
|
||||
- **THEN** they understand that Anthropic hasn't released an official offline tokenizer
|
||||
- **AND** they understand both methods are approximations based on similar BPE tokenizers
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Context Usage Reporting Hook Example
|
||||
The hooks lesson SHALL include a correct, working example showing how to create a hook that reports context/token usage after each Claude response.
|
||||
|
||||
#### Scenario: Token calculation is correct
|
||||
- **WHEN** a user copies the context-usage.py example
|
||||
- **AND** runs it as a Stop hook
|
||||
- **THEN** the hook correctly calculates estimated tokens from total character count
|
||||
- **AND** displays a non-zero token count proportional to conversation length
|
||||
|
||||
#### Scenario: User learns to create context monitoring hook
|
||||
- **WHEN** a user reads the context usage reporter example
|
||||
- **THEN** they find a complete Python script that reads the transcript file
|
||||
- **AND** they understand how to estimate token usage from conversation history
|
||||
- **AND** they see the configuration for Stop hooks
|
||||
- **AND** they understand the limitations of token estimation
|
||||
|
||||
#### Scenario: Hook output format is documented
|
||||
- **WHEN** a user implements the context usage hook
|
||||
- **THEN** they can generate a one-line report showing used tokens and remaining capacity
|
||||
- **AND** the output shows realistic token counts based on conversation size
|
||||
|
||||
#### Scenario: Delta-based tracking is documented
|
||||
- **WHEN** a user wants per-request token consumption
|
||||
- **THEN** they find documentation pointing to the pre-message/post-response hook pair approach
|
||||
- **AND** they understand how to use `UserPromptSubmit` + `Stop` for delta calculation
|
||||
@@ -0,0 +1,36 @@
|
||||
# Tasks: Add Context Usage Tracking Documentation
|
||||
|
||||
## 1. Documentation Updates
|
||||
|
||||
- [x] 1.1 Add "Context Tracking Hook Pairs" section to README explaining pre-message/post-response concept
|
||||
- [x] 1.2 Document how UserPromptSubmit serves as pre-message hook
|
||||
- [x] 1.3 Document how Stop serves as post-response hook
|
||||
- [x] 1.4 Explain token delta calculation methodology
|
||||
|
||||
## 2. Example Scripts
|
||||
|
||||
- [x] 2.1 Create `context-tracker.py` example script with character estimation (zero dependencies)
|
||||
- [x] 2.2 Create `context-tracker-tiktoken.py` example script with tiktoken method (more accurate)
|
||||
- [x] 2.3 Implement UserPromptSubmit handler (save pre-message count)
|
||||
- [x] 2.4 Implement Stop handler (calculate and report delta)
|
||||
- [x] 2.5 Add clear inline comments explaining both approaches
|
||||
|
||||
## 3. Configuration Examples
|
||||
|
||||
- [x] 3.1 Add hook configuration example for UserPromptSubmit event
|
||||
- [x] 3.2 Add hook configuration example for Stop event
|
||||
- [x] 3.3 Provide combined configuration showing both hooks together
|
||||
|
||||
## 4. Token Counting Methods Documentation
|
||||
|
||||
- [x] 4.1 Document tiktoken with p50k_base method (more accurate, ~90-95%)
|
||||
- [x] 4.2 Document character-based estimation method (simple, ~80-90%)
|
||||
- [x] 4.3 Create comparison table of both offline methods
|
||||
- [x] 4.4 Explain what's included/excluded from transcript
|
||||
- [x] 4.5 Add caveat that no official Claude offline tokenizer exists
|
||||
|
||||
## 5. Validation
|
||||
|
||||
- [x] 5.1 Test example script with sample JSON input
|
||||
- [x] 5.2 Verify configuration examples have valid JSON syntax
|
||||
- [x] 5.3 Run openspec validate to confirm proposal is complete
|
||||
@@ -0,0 +1,23 @@
|
||||
# Change: Add Blog Post - 4 Essential Slash Commands for Development Workflow
|
||||
|
||||
## Why
|
||||
|
||||
The claude-howto project provides excellent reference documentation but lacks blog-style content that showcases real-world usage patterns. Users have found 4 slash commands particularly valuable across their development workflow, and a blog post explaining when/where/how to use each would help others adopt these productivity tools.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Create new `blog-post/` directory for blog content
|
||||
- Add blog post: "4 Essential Slash Commands I Use in Every Project"
|
||||
- Cover 4 commands with practical guidance:
|
||||
- `/push-all` - Quick deployment of coherent changes
|
||||
- `/setup-ci-cd` - Post-POC quality infrastructure
|
||||
- `/doc-refactor` - Post-MVP documentation polish
|
||||
- `/unit-test-expand` - Milestone-driven test expansion
|
||||
- Reference the first slash commands blog: [Discovering Claude Code Slash Commands](https://medium.com/@luongnv89/discovering-claude-code-slash-commands-cdc17f0dfb29)
|
||||
- Link to full command files when content exceeds 30 lines
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected specs: None (new capability)
|
||||
- Affected code: New `blog-post/` directory and content
|
||||
- No breaking changes
|
||||
+41
@@ -0,0 +1,41 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Blog Post Directory Structure
|
||||
|
||||
The project SHALL provide a `blog-post/` directory for hosting blog-style content that complements the reference documentation.
|
||||
|
||||
#### Scenario: Blog post directory exists
|
||||
- **WHEN** a user navigates to the project root
|
||||
- **THEN** a `blog-post/` directory is present containing blog content
|
||||
|
||||
### Requirement: Slash Commands Usage Blog Post
|
||||
|
||||
The blog SHALL document 4 essential slash commands with practical usage guidance covering when, where, and how to use each command in a development workflow.
|
||||
|
||||
#### Scenario: Complete command coverage
|
||||
- **WHEN** a user reads the blog post
|
||||
- **THEN** they find documentation for `/push-all`, `/setup-ci-cd`, `/doc-refactor`, and `/unit-test-expand`
|
||||
|
||||
#### Scenario: Command file linking for long content
|
||||
- **WHEN** a command file exceeds 30 lines
|
||||
- **THEN** the blog SHALL provide a link to the full command file in the claude-howto project
|
||||
|
||||
#### Scenario: Inline content for short commands
|
||||
- **WHEN** a command file is 30 lines or fewer
|
||||
- **THEN** the blog MAY include the command content inline
|
||||
|
||||
### Requirement: Development Workflow Context
|
||||
|
||||
Each command section SHALL explain when to use the command in the development lifecycle (POC, MVP, milestone phases).
|
||||
|
||||
#### Scenario: Workflow phase guidance
|
||||
- **WHEN** a user reads a command section
|
||||
- **THEN** they understand which development phase the command is most appropriate for
|
||||
|
||||
### Requirement: Reference to First Blog
|
||||
|
||||
The blog post SHALL reference the introductory slash commands blog: "Discovering Claude Code Slash Commands" for foundational context.
|
||||
|
||||
#### Scenario: Blog reference present
|
||||
- **WHEN** a user reads the introduction
|
||||
- **THEN** they find a link to the original slash commands blog post on Medium
|
||||
@@ -0,0 +1,25 @@
|
||||
## 1. Setup
|
||||
|
||||
- [x] 1.1 Create `blog-post/` directory at project root
|
||||
|
||||
## 2. Blog Post Creation
|
||||
|
||||
- [x] 2.1 Create blog post markdown file with proper structure
|
||||
- [x] 2.2 Write introduction referencing first slash commands blog
|
||||
- [x] 2.3 Document `/push-all` with link to full command (152 lines)
|
||||
- [x] 2.4 Document `/setup-ci-cd` with inline content (25 lines)
|
||||
- [x] 2.5 Document `/doc-refactor` with inline content (23 lines)
|
||||
- [x] 2.6 Document `/unit-test-expand` with inline content (24 lines)
|
||||
- [x] 2.7 Add workflow diagram showing when to use each command
|
||||
- [x] 2.8 Write conclusion with development lifecycle integration
|
||||
|
||||
## 3. Integration
|
||||
|
||||
- [x] 3.1 Add blog-post to main README navigation
|
||||
- [x] 3.2 Cross-reference from slash-commands README
|
||||
|
||||
## 4. Verification
|
||||
|
||||
- [x] 4.1 Verify all internal links work
|
||||
- [x] 4.2 Verify external links are valid
|
||||
- [x] 4.3 Review content for clarity and accuracy
|
||||
@@ -0,0 +1,20 @@
|
||||
# Change: Update Slash Commands README with New Commands
|
||||
|
||||
## Why
|
||||
|
||||
The `01-slash-commands/README.md` is outdated and needs to reflect:
|
||||
1. Updated `push-all.md` command with enhanced safety checks (API key validation, confirmation workflow)
|
||||
2. Three new slash commands added to the folder: `doc-refactor.md`, `setup-ci-cd.md`, `unit-test-expand.md`
|
||||
|
||||
## What Changes
|
||||
|
||||
- **Update push-all documentation**: Reflect the enhanced workflow including safety checks, API key validation, and confirmation prompts
|
||||
- **Add doc-refactor command**: Document the new documentation restructuring command
|
||||
- **Add setup-ci-cd command**: Document the new CI/CD pipeline setup command
|
||||
- **Add unit-test-expand command**: Document the new test coverage expansion command
|
||||
- Update "Available Commands" section count from 4 to 7 commands
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected specs: `slash-commands`
|
||||
- Affected code: `01-slash-commands/README.md`
|
||||
@@ -0,0 +1,66 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Push-All Command with Safety Checks
|
||||
|
||||
The documentation SHALL describe the `/push-all` command with its comprehensive safety workflow including:
|
||||
1. Change analysis (git status, diff, log)
|
||||
2. Safety checks for secrets, API keys, large files, build artifacts
|
||||
3. API key validation distinguishing real keys from placeholders
|
||||
4. Confirmation prompt before proceeding
|
||||
5. Conventional commit message generation
|
||||
6. Error handling guidance
|
||||
|
||||
#### Scenario: User learns push-all safety workflow
|
||||
- **WHEN** a user reads the push-all command documentation
|
||||
- **THEN** they understand the multi-step safety workflow
|
||||
- **AND** they know what types of files trigger warnings
|
||||
- **AND** they understand they must confirm before execution
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Doc-Refactor Command Documentation
|
||||
|
||||
The documentation SHALL describe the `/doc-refactor` command for restructuring project documentation including:
|
||||
1. Project type analysis (library, API, web app, CLI, microservices)
|
||||
2. Documentation centralization in `docs/` folder
|
||||
3. Root README streamlining
|
||||
4. Component-level documentation
|
||||
5. Guide creation based on project type
|
||||
|
||||
#### Scenario: User uses doc-refactor command
|
||||
- **WHEN** a user reads the doc-refactor documentation
|
||||
- **THEN** they understand how to invoke the command
|
||||
- **AND** they know what documentation structure changes to expect
|
||||
- **AND** they understand the command adapts to project type
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Setup-CI-CD Command Documentation
|
||||
|
||||
The documentation SHALL describe the `/setup-ci-cd` command for implementing quality gates including:
|
||||
1. Project analysis for language and tooling detection
|
||||
2. Pre-commit hook configuration with language-specific tools
|
||||
3. GitHub Actions workflow creation
|
||||
4. Pipeline verification steps
|
||||
|
||||
#### Scenario: User uses setup-ci-cd command
|
||||
- **WHEN** a user reads the setup-ci-cd documentation
|
||||
- **THEN** they understand the command creates pre-commit hooks
|
||||
- **AND** they know GitHub Actions workflows will be generated
|
||||
- **AND** they understand tools are selected based on project language
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Unit-Test-Expand Command Documentation
|
||||
|
||||
The documentation SHALL describe the `/unit-test-expand` command for increasing test coverage including:
|
||||
1. Coverage analysis to identify gaps
|
||||
2. Gap identification (branches, error paths, boundaries)
|
||||
3. Framework-specific test generation
|
||||
4. Coverage verification
|
||||
|
||||
#### Scenario: User uses unit-test-expand command
|
||||
- **WHEN** a user reads the unit-test-expand documentation
|
||||
- **THEN** they understand the command analyzes existing coverage
|
||||
- **AND** they know it targets untested branches and edge cases
|
||||
- **AND** they understand it works with their project's testing framework
|
||||
@@ -0,0 +1,7 @@
|
||||
## 1. Implementation
|
||||
|
||||
- [x] 1.1 Update `/push-all` section in README to reflect enhanced safety checks (API key validation, confirmation workflow, detailed error handling)
|
||||
- [x] 1.2 Add `/doc-refactor` section documenting the documentation restructuring command
|
||||
- [x] 1.3 Add `/setup-ci-cd` section documenting the CI/CD pipeline setup command
|
||||
- [x] 1.4 Add `/unit-test-expand` section documenting the test coverage expansion command
|
||||
- [x] 1.5 Update section heading to reflect 8 available commands (was 4, added 4 new)
|
||||
@@ -0,0 +1,44 @@
|
||||
# blog-post Specification
|
||||
|
||||
## Purpose
|
||||
TBD - created by archiving change add-blog-post-slash-commands. Update Purpose after archive.
|
||||
## Requirements
|
||||
### Requirement: Blog Post Directory Structure
|
||||
|
||||
The project SHALL provide a `blog-post/` directory for hosting blog-style content that complements the reference documentation.
|
||||
|
||||
#### Scenario: Blog post directory exists
|
||||
- **WHEN** a user navigates to the project root
|
||||
- **THEN** a `blog-post/` directory is present containing blog content
|
||||
|
||||
### Requirement: Slash Commands Usage Blog Post
|
||||
|
||||
The blog SHALL document 4 essential slash commands with practical usage guidance covering when, where, and how to use each command in a development workflow.
|
||||
|
||||
#### Scenario: Complete command coverage
|
||||
- **WHEN** a user reads the blog post
|
||||
- **THEN** they find documentation for `/push-all`, `/setup-ci-cd`, `/doc-refactor`, and `/unit-test-expand`
|
||||
|
||||
#### Scenario: Command file linking for long content
|
||||
- **WHEN** a command file exceeds 30 lines
|
||||
- **THEN** the blog SHALL provide a link to the full command file in the claude-howto project
|
||||
|
||||
#### Scenario: Inline content for short commands
|
||||
- **WHEN** a command file is 30 lines or fewer
|
||||
- **THEN** the blog MAY include the command content inline
|
||||
|
||||
### Requirement: Development Workflow Context
|
||||
|
||||
Each command section SHALL explain when to use the command in the development lifecycle (POC, MVP, milestone phases).
|
||||
|
||||
#### Scenario: Workflow phase guidance
|
||||
- **WHEN** a user reads a command section
|
||||
- **THEN** they understand which development phase the command is most appropriate for
|
||||
|
||||
### Requirement: Reference to First Blog
|
||||
|
||||
The blog post SHALL reference the introductory slash commands blog: "Discovering Claude Code Slash Commands" for foundational context.
|
||||
|
||||
#### Scenario: Blog reference present
|
||||
- **WHEN** a user reads the introduction
|
||||
- **THEN** they find a link to the original slash commands blog post on Medium
|
||||
Reference in New Issue
Block a user