github-code/claude-howto
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Add blog post and new slash commands for development workflow

Browse Source 
- 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
2025-12-26 11:02:19 +01:00
parent 8ef1e4a0c0
commit 0fcac18357
21 changed files with 1557 additions and 397 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
01-slash-commands/README.md
View File

@@ -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/)
---

24
01-slash-commands/doc-refactor.md Normal file
View File

@@ -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.

472
01-slash-commands/push-all.md
View File

@@ -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.

25
01-slash-commands/setup-ci-cd.md Normal file
View File

@@ -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.

25
01-slash-commands/unit-test-expand.md Normal file
View File

@@ -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.