mirror of
https://github.com/duthaho/claudekit.git
synced 2026-08-07 20:20:19 +03:00
feat: migrate commands to skills
This commit is contained in:
duthaho
@@ -1,5 +1,6 @@
|
||||
---
|
||||
name: brainstorming
|
||||
argument-hint: "[topic]"
|
||||
description: >
|
||||
Use when the user wants to design, explore, or ideate on ANY new feature, architecture decision, or unclear requirement. Activate for keywords like "brainstorm", "design", "explore", "what if", "how should we", "options for", "trade-offs", or any open-ended question about implementation approach. Also trigger when requirements are vague, ambiguous, or when multiple valid solutions exist -- err on the side of brainstorming before jumping into code.
|
||||
---
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
name: condition-based-waiting
|
||||
user-invocable: false
|
||||
description: >
|
||||
Use when waiting on external conditions like CI pipeline runs, deployments, long builds, database migrations, or test suites. Trigger for keywords like "wait for", "check status", "poll", "monitor", "is it done", "build running", "deploy in progress", or when a background process needs to complete before the next step. Also activate when using run_in_background or Monitor tools in Claude Code.
|
||||
---
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
name: defense-in-depth
|
||||
user-invocable: false
|
||||
description: >
|
||||
Use when fixing any data-related bug, when building validation for critical data paths, or when a single validation point has already failed in production. Also activate whenever you hear "it slipped through," "the check was bypassed," or "it worked in tests but not production." Apply aggressively to any scenario involving data integrity, input validation across layers, or preventing bug recurrence through structural guarantees rather than single-point fixes.
|
||||
---
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: devops
|
||||
description: >
|
||||
Use when containerizing applications, configuring CI/CD pipelines, or deploying to edge — including Docker, Dockerfile, docker-compose, multi-stage builds, GitHub Actions, workflow YAML, matrix builds, workflow_dispatch, Cloudflare Workers, Pages, R2, D1, KV, wrangler, or container registries.
|
||||
Use when containerizing applications, configuring CI/CD pipelines, deploying to environments, or deploying to edge — including Docker, Dockerfile, docker-compose, multi-stage builds, GitHub Actions, workflow YAML, matrix builds, workflow_dispatch, Cloudflare Workers, Pages, R2, D1, KV, wrangler, container registries, or deployment workflows (staging, production, health checks, smoke tests).
|
||||
---
|
||||
|
||||
# DevOps
|
||||
@@ -11,6 +11,8 @@ description: >
|
||||
- Containerizing applications with Docker or Docker Compose
|
||||
- Setting up CI/CD pipelines with GitHub Actions
|
||||
- Deploying to Cloudflare Workers, Pages, R2, D1, or KV
|
||||
- Deploying applications to staging or production environments
|
||||
- Running pre-deploy checks (build, tests, security audit)
|
||||
- Optimizing container images, build caching, or deployment workflows
|
||||
- Configuring wrangler.toml, Durable Objects, or Cloudflare Queues
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: dispatching-parallel-agents
|
||||
description: >
|
||||
Use when facing 3 or more independent failures across different domains, when multiple subsystems are broken with no shared state, or when test failures span unrelated modules. Also activate whenever you see independent bugs in auth, cart, user, or other separate domains that can be fixed concurrently. Activate aggressively for any scenario where parallel work would reduce total resolution time without creating merge conflicts.
|
||||
Use when facing 3 or more independent failures across different domains, when multiple subsystems are broken with no shared state, or when test failures span unrelated modules. Also activate whenever you see independent bugs in auth, cart, user, or other separate domains that can be fixed concurrently. Use for launching parallel background tasks like research, analysis, or code review across independent areas. Activate aggressively for any scenario where parallel work would reduce total resolution time without creating merge conflicts.
|
||||
---
|
||||
|
||||
# Dispatching Parallel Agents
|
||||
|
||||
@@ -0,0 +1,82 @@
|
||||
---
|
||||
name: documentation
|
||||
argument-hint: "[file or api/readme]"
|
||||
description: >
|
||||
Use when generating or updating documentation — including code comments, docstrings, JSDoc, API docs, README files, or technical specifications. Trigger for keywords like "document", "docstring", "JSDoc", "README", "API docs", "explain this code", "add comments", or any request to improve code documentation. Also activate when generating project documentation or updating existing docs after code changes.
|
||||
---
|
||||
|
||||
# Documentation
|
||||
|
||||
## When to Use
|
||||
|
||||
- Adding docstrings or JSDoc to functions/classes
|
||||
- Generating or updating README files
|
||||
- Documenting API endpoints
|
||||
- Writing technical specifications
|
||||
- Adding inline comments to complex logic
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
- Generating changelogs from commits — use `git-workflows`
|
||||
- Writing OpenAPI specs — use `openapi`
|
||||
- Architecture design documentation — use `brainstorming` + `writing-plans`
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Topic | Reference | Key content |
|
||||
|-------|-----------|-------------|
|
||||
| Code documentation | `references/code-docs.md` | Python docstrings, TypeScript JSDoc, inline comments |
|
||||
| API documentation | `references/api-docs.md` | Endpoint docs, request/response examples |
|
||||
| Project documentation | `references/project-docs.md` | README, CONTRIBUTING, architecture docs |
|
||||
|
||||
---
|
||||
|
||||
## Documentation Workflow
|
||||
|
||||
### For Code
|
||||
|
||||
1. Read the code thoroughly — understand purpose and behavior
|
||||
2. Identify inputs, outputs, side effects, and edge cases
|
||||
3. Add docstrings/JSDoc with examples
|
||||
4. Add type annotations if missing
|
||||
|
||||
### For APIs
|
||||
|
||||
1. Scan route definitions and identify endpoints
|
||||
2. Document request format, response format, error responses
|
||||
3. Add authentication requirements
|
||||
4. Include working examples
|
||||
|
||||
### For Projects
|
||||
|
||||
1. Analyze project purpose, features, and setup
|
||||
2. Write clear installation and usage instructions
|
||||
3. Include working code examples
|
||||
4. Keep configuration tables up to date
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Document the why, not the what** — code shows what; comments explain why.
|
||||
2. **Include examples** — one working example beats three paragraphs of description.
|
||||
3. **Document edge cases** — what happens with null, empty, or invalid input?
|
||||
4. **Keep docs adjacent to code** — docstrings over separate doc files.
|
||||
5. **Update docs with code** — stale docs are worse than no docs.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
1. **Restating the code** — `# increment i by 1` adds no value.
|
||||
2. **Missing error documentation** — not documenting what exceptions a function raises.
|
||||
3. **Outdated examples** — code examples that no longer compile.
|
||||
4. **Over-documenting internal code** — public APIs need docs; private helpers often don't.
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `openapi` — OpenAPI spec generation for REST APIs
|
||||
- `git-workflows` — Changelog generation from commits
|
||||
- `backend-frameworks` — Framework-specific documentation patterns
|
||||
@@ -0,0 +1,44 @@
|
||||
# API Documentation Patterns
|
||||
|
||||
## Endpoint Documentation Template
|
||||
|
||||
```markdown
|
||||
## POST /api/orders
|
||||
|
||||
Create a new order.
|
||||
|
||||
### Authentication
|
||||
Requires Bearer token.
|
||||
|
||||
### Request Body
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| items | array | yes | Order items |
|
||||
| shippingAddress | object | yes | Delivery address |
|
||||
|
||||
### Response (201 Created)
|
||||
```json
|
||||
{
|
||||
"id": "order_456",
|
||||
"status": "pending",
|
||||
"total": 99.99,
|
||||
"createdAt": "2024-01-15T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Errors
|
||||
| Status | Code | Description |
|
||||
|--------|------|-------------|
|
||||
| 400 | INVALID_ITEMS | Items array is empty |
|
||||
| 401 | UNAUTHORIZED | Invalid or missing token |
|
||||
| 422 | OUT_OF_STOCK | Item not available |
|
||||
```
|
||||
|
||||
## Discovery Process
|
||||
|
||||
1. Scan route definitions (`@app.get`, `router.post`, `@Controller`)
|
||||
2. Identify HTTP methods and paths
|
||||
3. Note authentication requirements
|
||||
4. Document request/response schemas
|
||||
5. List all error responses with codes
|
||||
6. Add working curl/httpx examples
|
||||
@@ -0,0 +1,52 @@
|
||||
# Code Documentation Patterns
|
||||
|
||||
## Python Docstrings (Google Style)
|
||||
|
||||
```python
|
||||
def calculate_discount(price: float, percentage: float) -> float:
|
||||
"""Calculate discounted price.
|
||||
|
||||
Args:
|
||||
price: Original price in dollars.
|
||||
percentage: Discount percentage (0-100).
|
||||
|
||||
Returns:
|
||||
The discounted price.
|
||||
|
||||
Raises:
|
||||
ValueError: If percentage is not between 0 and 100.
|
||||
|
||||
Example:
|
||||
>>> calculate_discount(100.0, 20)
|
||||
80.0
|
||||
"""
|
||||
```
|
||||
|
||||
## TypeScript JSDoc
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* Calculate discounted price.
|
||||
*
|
||||
* @param price - Original price in dollars
|
||||
* @param percentage - Discount percentage (0-100)
|
||||
* @returns The discounted price
|
||||
* @throws {RangeError} If percentage is not between 0 and 100
|
||||
*
|
||||
* @example
|
||||
* calculateDiscount(100, 20); // returns 80
|
||||
*/
|
||||
```
|
||||
|
||||
## When to Add Inline Comments
|
||||
|
||||
- Explain **why**, not what — `# Retry 3x because upstream API is flaky`
|
||||
- Document workarounds — `// Safari doesn't support this API, fallback to...`
|
||||
- Clarify non-obvious logic — `# O(1) amortized via lazy deletion`
|
||||
- Mark TODOs with context — `# TODO(#123): remove after migration complete`
|
||||
|
||||
## When NOT to Comment
|
||||
|
||||
- Restating the code: `i += 1 # increment i by 1`
|
||||
- Obvious function names: `def get_user_by_id` needs no docstring explaining it gets a user by ID
|
||||
- Commented-out code — delete it, git has history
|
||||
@@ -0,0 +1,43 @@
|
||||
# Project Documentation Patterns
|
||||
|
||||
## README Structure
|
||||
|
||||
```markdown
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install my-package
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
```typescript
|
||||
import { Client } from 'my-package';
|
||||
const client = new Client({ apiKey: 'your-key' });
|
||||
const result = await client.fetch();
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `apiKey` | string | required | Your API key |
|
||||
| `timeout` | number | 5000 | Request timeout in ms |
|
||||
```
|
||||
|
||||
## Key Sections
|
||||
|
||||
1. **Title + one-liner** — what this project does
|
||||
2. **Installation** — copy-pasteable setup commands
|
||||
3. **Quick Start** — working example in < 10 lines
|
||||
4. **Configuration** — table of options with types and defaults
|
||||
5. **API Reference** — link to detailed docs
|
||||
6. **Contributing** — how to contribute
|
||||
7. **License** — MIT, Apache, etc.
|
||||
|
||||
## Documentation Coverage Report
|
||||
|
||||
After documenting, summarize:
|
||||
- Functions documented: X/Y (Z%)
|
||||
- Endpoints documented: X/Y (Z%)
|
||||
- Missing: [list of undocumented items]
|
||||
@@ -0,0 +1,135 @@
|
||||
---
|
||||
name: feature-workflow
|
||||
argument-hint: "[feature description or issue]"
|
||||
description: >
|
||||
Use when implementing a complete feature end-to-end — from requirements analysis through planning, implementation, testing, and review. Trigger for keywords like "feature", "implement", "build", "add functionality", "end-to-end", or any task that spans planning through delivery. Also activate when the user provides a feature description, issue reference, or requirement spec that needs a structured development workflow.
|
||||
---
|
||||
|
||||
# Feature Workflow
|
||||
|
||||
## When to Use
|
||||
|
||||
- Implementing a complete feature from requirements to delivery
|
||||
- When given a feature description, issue number, or requirement spec
|
||||
- Multi-phase work that needs planning, implementation, testing, and review
|
||||
- Any task that benefits from a structured development workflow
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
- Simple bug fixes — use `systematic-debugging`
|
||||
- Pure refactoring — use `refactoring`
|
||||
- Writing tests for existing code — use `testing`
|
||||
- Already have a plan to execute — use `executing-plans`
|
||||
|
||||
---
|
||||
|
||||
## Workflow Phases
|
||||
|
||||
### Phase 1: Understanding
|
||||
|
||||
1. Parse the feature request thoroughly
|
||||
2. Identify acceptance criteria
|
||||
3. List assumptions that need validation
|
||||
4. Clarify ambiguous requirements with the user
|
||||
|
||||
### Phase 2: Planning
|
||||
|
||||
1. Explore codebase for related implementations and patterns
|
||||
2. Identify integration points and dependencies
|
||||
3. Decompose into atomic, verifiable tasks
|
||||
4. Order tasks by dependencies
|
||||
5. Track all tasks with TodoWrite
|
||||
|
||||
### Phase 3: Research (if needed)
|
||||
|
||||
If the feature involves unfamiliar technology:
|
||||
1. Research best practices and patterns
|
||||
2. Find examples in the codebase or documentation
|
||||
3. Identify potential pitfalls
|
||||
|
||||
### Phase 4: Implementation
|
||||
|
||||
For each task:
|
||||
1. Write failing test first (TDD)
|
||||
2. Implement minimally to pass the test
|
||||
3. Refactor if needed
|
||||
4. Mark task complete immediately
|
||||
|
||||
### Phase 5: Testing
|
||||
|
||||
1. Run full test suite — no regressions
|
||||
2. Verify coverage — should not decrease
|
||||
3. Test edge cases and error scenarios
|
||||
|
||||
```bash
|
||||
# Python
|
||||
pytest -v --cov=src
|
||||
|
||||
# TypeScript
|
||||
pnpm test
|
||||
```
|
||||
|
||||
### Phase 6: Review
|
||||
|
||||
Self-review checklist:
|
||||
- [ ] Code follows project conventions
|
||||
- [ ] No security vulnerabilities
|
||||
- [ ] Error handling is complete
|
||||
- [ ] Tests are passing
|
||||
- [ ] No debug statements or TODOs
|
||||
|
||||
### Phase 7: Completion
|
||||
|
||||
1. Verify all tasks complete
|
||||
2. Stage appropriate files
|
||||
3. Generate commit message
|
||||
4. Create PR if requested
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
```markdown
|
||||
## Feature Implementation Complete
|
||||
|
||||
### Feature
|
||||
[Feature description]
|
||||
|
||||
### Changes Made
|
||||
- `path/to/file.ts` — [What was added/modified]
|
||||
- `path/to/file.test.ts` — [Tests added]
|
||||
|
||||
### Tests
|
||||
- [x] Unit tests passing
|
||||
- [x] Integration tests passing
|
||||
- [x] Coverage: XX%
|
||||
|
||||
### Ready for Review
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Break down aggressively** — smaller tasks are easier to verify and commit.
|
||||
2. **Test first** — every task starts with a failing test.
|
||||
3. **Commit incrementally** — commit after each task, not at the end.
|
||||
4. **Clarify before building** — ambiguous requirements lead to rework.
|
||||
5. **Check existing patterns** — follow conventions already in the codebase.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
1. **Starting without understanding** — jumping to code before clarifying requirements.
|
||||
2. **Monolithic implementation** — implementing everything in one pass without incremental verification.
|
||||
3. **Ignoring existing patterns** — building something inconsistent with the rest of the codebase.
|
||||
4. **Skipping tests** — "I'll add tests later" means no tests.
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `brainstorming` — Use before this skill when requirements are unclear or need exploration
|
||||
- `writing-plans` — Use for detailed task breakdown when the feature is complex
|
||||
- `test-driven-development` — The TDD discipline applied during Phase 4
|
||||
- `git-workflows` — Committing and shipping the completed feature
|
||||
- `requesting-code-review` — Getting feedback before merging
|
||||
@@ -0,0 +1,119 @@
|
||||
---
|
||||
name: git-workflows
|
||||
argument-hint: "[commit/ship/pr/changelog]"
|
||||
description: >
|
||||
Use when committing code, creating pull requests, shipping changes, or generating changelogs. Trigger for keywords like "commit", "push", "PR", "pull request", "ship", "merge", "changelog", "release notes", "conventional commits", or any git workflow beyond basic status/diff. Also activate when preparing code for review or automating the commit-to-PR pipeline.
|
||||
---
|
||||
|
||||
# Git Workflows
|
||||
|
||||
## When to Use
|
||||
|
||||
- Creating commits with conventional commit messages
|
||||
- Shipping code (commit + review + push + PR)
|
||||
- Creating pull requests with proper descriptions
|
||||
- Generating changelogs from commit history
|
||||
- Preparing code for review or merge
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
- Basic git operations (status, diff, log) — just run them directly
|
||||
- Branch management strategy — use `using-git-worktrees`
|
||||
- Code review content — use `requesting-code-review`
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Workflow | Reference | Key content |
|
||||
|----------|-----------|-------------|
|
||||
| Committing | `references/committing.md` | Conventional commits, message format, pre-commit checks |
|
||||
| Shipping | `references/shipping.md` | Full ship workflow: review → test → commit → push → PR |
|
||||
| Pull Requests | `references/pull-requests.md` | PR creation, description templates, gh CLI patterns |
|
||||
| Changelogs | `references/changelogs.md` | Changelog generation from commits, Keep a Changelog format |
|
||||
|
||||
---
|
||||
|
||||
## Conventional Commit Format
|
||||
|
||||
```
|
||||
type(scope): subject
|
||||
|
||||
body (optional)
|
||||
|
||||
footer (optional)
|
||||
```
|
||||
|
||||
| Type | When |
|
||||
|------|------|
|
||||
| `feat` | New feature |
|
||||
| `fix` | Bug fix |
|
||||
| `docs` | Documentation only |
|
||||
| `refactor` | Code restructuring, no behavior change |
|
||||
| `test` | Adding or fixing tests |
|
||||
| `chore` | Maintenance, dependencies, CI |
|
||||
| `style` | Formatting, whitespace |
|
||||
|
||||
### Subject Line Rules
|
||||
|
||||
- Max 50 characters, imperative mood ("Add" not "Added"), no trailing period
|
||||
|
||||
---
|
||||
|
||||
## Ship Workflow
|
||||
|
||||
```
|
||||
1. Pre-ship checks (secrets, debug statements)
|
||||
2. Self-review (code quality, style)
|
||||
3. Run tests (full suite, coverage check)
|
||||
4. Create commit (conventional format)
|
||||
5. Push to remote
|
||||
6. Create PR (summary, test plan, checklist)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PR Description Template
|
||||
|
||||
```markdown
|
||||
## Summary
|
||||
- [Change 1]
|
||||
- [Change 2]
|
||||
|
||||
## Test Plan
|
||||
- [ ] Unit tests pass
|
||||
- [ ] Manual testing done
|
||||
|
||||
## Checklist
|
||||
- [ ] No breaking changes
|
||||
- [ ] Tests added/updated
|
||||
- [ ] Documentation updated
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Atomic commits** — one logical change per commit, not one file per commit.
|
||||
2. **Explain why, not what** — the diff shows what changed; the message explains why.
|
||||
3. **Stage specific files** — prefer `git add <file>` over `git add -A` to avoid committing secrets or unrelated changes.
|
||||
4. **Reference issues** — include `Closes #123` or `Fixes #456` in footers.
|
||||
5. **Pre-commit checks** — verify no secrets, debug statements, or commented-out code before committing.
|
||||
6. **PR descriptions matter** — reviewers read the description before the diff; make it count.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
1. **Committing secrets** — `.env` files, API keys, tokens in staged changes.
|
||||
2. **Vague commit messages** — "fix stuff", "updates", "WIP" provide no context.
|
||||
3. **Giant PRs** — 500+ line PRs get rubber-stamped; split into focused chunks.
|
||||
4. **Amending published commits** — rewriting history others have pulled causes conflicts.
|
||||
5. **Skipping pre-commit hooks** — `--no-verify` hides real issues.
|
||||
6. **Force pushing to shared branches** — can destroy teammates' work.
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `requesting-code-review` — Preparing changes for reviewer feedback
|
||||
- `finishing-a-development-branch` — End-of-branch workflow decisions
|
||||
- `using-git-worktrees` — Isolated branch management
|
||||
@@ -0,0 +1,59 @@
|
||||
# Changelog Generation
|
||||
|
||||
## Keep a Changelog Format
|
||||
|
||||
Based on [keepachangelog.com](https://keepachangelog.com):
|
||||
|
||||
```markdown
|
||||
## [1.2.0] - 2026-04-19
|
||||
|
||||
### Added
|
||||
- Password reset functionality (#123)
|
||||
- Email verification for new accounts
|
||||
|
||||
### Changed
|
||||
- Improved error messages for validation failures
|
||||
- Updated dependencies to latest versions
|
||||
|
||||
### Fixed
|
||||
- Race condition in session handling (#456)
|
||||
- Incorrect timezone in date displays
|
||||
|
||||
### Removed
|
||||
- Legacy v1 API endpoints (deprecated since 1.0)
|
||||
```
|
||||
|
||||
## Generating from Commits
|
||||
|
||||
```bash
|
||||
# Get commits since last tag
|
||||
git log --oneline $(git describe --tags --abbrev=0)..HEAD
|
||||
|
||||
# Group by type
|
||||
git log --oneline --grep="^feat" $(git describe --tags --abbrev=0)..HEAD
|
||||
git log --oneline --grep="^fix" $(git describe --tags --abbrev=0)..HEAD
|
||||
```
|
||||
|
||||
## Category Mapping
|
||||
|
||||
| Commit Type | Changelog Category |
|
||||
|-------------|-------------------|
|
||||
| `feat` | Added |
|
||||
| `fix` | Fixed |
|
||||
| `refactor`, `perf` | Changed |
|
||||
| removal commits | Removed |
|
||||
| `docs` | Usually omitted |
|
||||
| `chore`, `test`, `style` | Usually omitted |
|
||||
|
||||
## User-Friendly Descriptions
|
||||
|
||||
Transform commit messages into user-facing descriptions:
|
||||
|
||||
```
|
||||
BAD: feat(auth): add pwd reset (#123)
|
||||
GOOD: Password reset functionality — users can now reset their password via email (#123)
|
||||
```
|
||||
|
||||
- Write for users, not developers
|
||||
- Include PR/issue references
|
||||
- Explain the user-visible impact
|
||||
@@ -0,0 +1,90 @@
|
||||
# Committing Patterns
|
||||
|
||||
## Pre-Commit Checklist
|
||||
|
||||
Before staging:
|
||||
- [ ] No secrets (`.env`, API keys, tokens)
|
||||
- [ ] No debug statements (`console.log`, `print()`, `debugger`)
|
||||
- [ ] No commented-out code blocks
|
||||
- [ ] Code is formatted (prettier/ruff)
|
||||
|
||||
## Conventional Commit Format
|
||||
|
||||
```
|
||||
type(scope): subject
|
||||
|
||||
body (optional - explain why, not what)
|
||||
|
||||
footer (optional - references, breaking changes)
|
||||
```
|
||||
|
||||
### Types
|
||||
|
||||
| Type | When | Example |
|
||||
|------|------|---------|
|
||||
| `feat` | New feature | `feat(auth): add OAuth2 login` |
|
||||
| `fix` | Bug fix | `fix(api): handle null user in profile` |
|
||||
| `docs` | Documentation | `docs(readme): update install steps` |
|
||||
| `refactor` | Restructure, no behavior change | `refactor(db): extract query builders` |
|
||||
| `test` | Add/fix tests | `test(auth): add login edge cases` |
|
||||
| `chore` | Maintenance | `chore(deps): update React to 19` |
|
||||
| `style` | Formatting | `style: apply prettier` |
|
||||
| `perf` | Performance | `perf(query): add index on user_id` |
|
||||
|
||||
### Subject Line Rules
|
||||
|
||||
- Max 50 characters
|
||||
- Imperative mood: "Add" not "Added" or "Adds"
|
||||
- No trailing period
|
||||
- Capitalize first letter
|
||||
|
||||
### Body Rules
|
||||
|
||||
- Wrap at 72 characters
|
||||
- Explain **why**, not what (the diff shows what)
|
||||
- Use bullet points for multiple changes
|
||||
|
||||
### Footer Patterns
|
||||
|
||||
```
|
||||
Closes #123
|
||||
Fixes #456
|
||||
BREAKING CHANGE: removed legacy auth endpoint
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>
|
||||
```
|
||||
|
||||
## Staging Best Practices
|
||||
|
||||
```bash
|
||||
# Prefer specific files over blanket add
|
||||
git add src/auth/login.ts src/auth/login.test.ts
|
||||
|
||||
# Review what you're committing
|
||||
git diff --staged
|
||||
|
||||
# Never commit these
|
||||
# .env, credentials.json, *.pem, *.key
|
||||
```
|
||||
|
||||
## Commit Command Pattern
|
||||
|
||||
```bash
|
||||
git commit -m "$(cat <<'EOF'
|
||||
feat(auth): add password reset flow
|
||||
|
||||
- Add reset token generation with 1h expiry
|
||||
- Implement email sending via SendGrid
|
||||
- Add rate limiting (3 requests/hour)
|
||||
|
||||
Closes #123
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
## Amending vs New Commit
|
||||
|
||||
- **Amend**: Only for unpushed commits, only when fixing the same logical change
|
||||
- **New commit**: Always for pushed commits, or when adding distinct changes
|
||||
- **Never amend after pre-commit hook failure** — the commit didn't happen, so amend would modify the previous commit
|
||||
@@ -0,0 +1,77 @@
|
||||
# Pull Request Patterns
|
||||
|
||||
## Pre-PR Checklist
|
||||
|
||||
- [ ] All tests passing
|
||||
- [ ] Code self-reviewed
|
||||
- [ ] No merge conflicts with base branch
|
||||
- [ ] Branch pushed to remote
|
||||
- [ ] Commit history is clean (no "WIP" or "fix typo" noise)
|
||||
|
||||
## Creating a PR
|
||||
|
||||
```bash
|
||||
# Check current state
|
||||
git status
|
||||
git diff main...HEAD
|
||||
git log --oneline main..HEAD
|
||||
|
||||
# Push if needed
|
||||
git push -u origin $(git branch --show-current)
|
||||
|
||||
# Create PR
|
||||
gh pr create --title "feat(scope): description" --body "$(cat <<'EOF'
|
||||
## Summary
|
||||
- [Change 1]
|
||||
- [Change 2]
|
||||
|
||||
## Test Plan
|
||||
- [ ] Unit tests added
|
||||
- [ ] Manual testing done
|
||||
- [ ] Edge cases covered
|
||||
|
||||
## Checklist
|
||||
- [ ] No breaking changes
|
||||
- [ ] Tests added/updated
|
||||
- [ ] Documentation updated
|
||||
|
||||
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
## PR Title Format
|
||||
|
||||
Follow conventional commits: `type(scope): description`
|
||||
|
||||
- Max 70 characters
|
||||
- Use description/body for details, not the title
|
||||
|
||||
## PR Size Guidelines
|
||||
|
||||
| Size | Lines Changed | Review Time |
|
||||
|------|--------------|-------------|
|
||||
| Small | < 100 | Quick review |
|
||||
| Medium | 100-300 | Thorough review |
|
||||
| Large | 300-500 | Split if possible |
|
||||
| Too Large | > 500 | Must split |
|
||||
|
||||
## Viewing PR Comments
|
||||
|
||||
```bash
|
||||
# View PR comments
|
||||
gh api repos/owner/repo/pulls/123/comments
|
||||
|
||||
# View PR review comments
|
||||
gh pr view 123 --comments
|
||||
```
|
||||
|
||||
## Draft PRs
|
||||
|
||||
```bash
|
||||
# Create as draft for early feedback
|
||||
gh pr create --draft --title "WIP: feature" --body "Early draft for feedback"
|
||||
|
||||
# Mark ready when done
|
||||
gh pr ready 123
|
||||
```
|
||||
@@ -0,0 +1,101 @@
|
||||
# Ship Workflow
|
||||
|
||||
Complete workflow: review → test → commit → push → PR.
|
||||
|
||||
## Phase 1: Pre-Ship Checks
|
||||
|
||||
```bash
|
||||
git status
|
||||
git diff --staged
|
||||
```
|
||||
|
||||
Verify:
|
||||
- [ ] No secrets in staged files
|
||||
- [ ] No debug statements
|
||||
- [ ] No commented-out code
|
||||
- [ ] No unintended files
|
||||
|
||||
## Phase 2: Self-Review
|
||||
|
||||
- Check code quality and style compliance
|
||||
- Verify security (no hardcoded secrets, proper input validation)
|
||||
- Address critical issues before proceeding
|
||||
|
||||
## Phase 3: Run Tests
|
||||
|
||||
```bash
|
||||
# Python
|
||||
pytest -v
|
||||
|
||||
# TypeScript
|
||||
pnpm test
|
||||
```
|
||||
|
||||
- All tests must pass
|
||||
- Coverage should not decrease
|
||||
- No new warnings
|
||||
|
||||
## Phase 4: Create Commit
|
||||
|
||||
```bash
|
||||
# Stage specific files
|
||||
git add src/feature.ts src/feature.test.ts
|
||||
|
||||
# Commit with conventional format
|
||||
git commit -m "$(cat <<'EOF'
|
||||
feat(scope): description
|
||||
|
||||
- Change 1
|
||||
- Change 2
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
## Phase 5: Push and Create PR
|
||||
|
||||
```bash
|
||||
# Push with upstream tracking
|
||||
git push -u origin feature/my-feature
|
||||
|
||||
# Create PR
|
||||
gh pr create --title "feat(scope): description" --body "$(cat <<'EOF'
|
||||
## Summary
|
||||
- Change 1
|
||||
- Change 2
|
||||
|
||||
## Test Plan
|
||||
- [ ] Unit tests pass
|
||||
- [ ] Manual testing done
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
## Quick Ship Mode
|
||||
|
||||
For small, low-risk changes:
|
||||
1. Skip detailed self-review
|
||||
2. Auto-generate commit message from diff
|
||||
3. Minimal PR description
|
||||
|
||||
## Ship Report Format
|
||||
|
||||
```markdown
|
||||
## Ship Complete
|
||||
|
||||
### Commit
|
||||
**Hash**: `abc1234`
|
||||
**Message**: `feat(auth): add password reset`
|
||||
|
||||
### Checks
|
||||
- [x] Tests passing (42 tests)
|
||||
- [x] Coverage: 85% (+3%)
|
||||
- [x] No security issues
|
||||
|
||||
### Pull Request
|
||||
**URL**: https://github.com/org/repo/pull/123
|
||||
**Status**: Ready for review
|
||||
```
|
||||
@@ -0,0 +1,91 @@
|
||||
---
|
||||
name: mode-switching
|
||||
argument-hint: "[mode name]"
|
||||
description: >
|
||||
Use when the user wants to switch behavioral modes for the session — adjusting communication style, output format, and problem-solving approach. Trigger for keywords like "mode", "switch mode", "brainstorm mode", "token-efficient", "deep-research mode", "implementation mode", "review mode", "orchestration mode", or any request to change how Claude responds for the remainder of the session.
|
||||
---
|
||||
|
||||
# Mode Switching
|
||||
|
||||
## When to Use
|
||||
|
||||
- User wants to change response style for the session
|
||||
- Switching between exploration and execution phases
|
||||
- Optimizing for token efficiency during high-volume work
|
||||
- Entering focused review or deep-research mode
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
- One-off format requests ("give me a shorter answer") — just comply directly
|
||||
- Switching tools or skills — modes affect style, not capabilities
|
||||
|
||||
---
|
||||
|
||||
## Available Modes
|
||||
|
||||
| Mode | Description | Best For |
|
||||
|------|-------------|----------|
|
||||
| `default` | Balanced responses, mix of explanation and code | General tasks |
|
||||
| `brainstorm` | More questions, multiple alternatives, explore trade-offs | Design, ideation |
|
||||
| `token-efficient` | Minimal explanations, code-only where possible | High-volume, cost savings |
|
||||
| `deep-research` | Thorough analysis, citations, confidence levels | Investigation, audits |
|
||||
| `implementation` | Jump straight to code, progress indicators | Executing plans |
|
||||
| `review` | Look for issues first, severity levels, actionable feedback | Code review, QA |
|
||||
| `orchestration` | Task breakdown, parallel execution, result aggregation | Complex parallel work |
|
||||
|
||||
## Mode Activation
|
||||
|
||||
```
|
||||
/mode brainstorm # Switch for session
|
||||
/mode # Show current mode
|
||||
/mode default # Reset
|
||||
```
|
||||
|
||||
## Per-Command Override
|
||||
|
||||
Modes can be overridden for a single command without changing the session mode:
|
||||
|
||||
```
|
||||
/feature --mode=implementation "add user profiles"
|
||||
/review --mode=deep-research src/auth/
|
||||
/plan --mode=brainstorm "design payment flow"
|
||||
```
|
||||
|
||||
## Recommended Workflows
|
||||
|
||||
### Feature Development
|
||||
|
||||
```
|
||||
brainstorm → implementation → review → default
|
||||
```
|
||||
|
||||
### Bug Investigation
|
||||
|
||||
```
|
||||
deep-research → implementation → default
|
||||
```
|
||||
|
||||
### Cost-Conscious Session
|
||||
|
||||
```
|
||||
token-efficient → [work on tasks] → default
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mode Files
|
||||
|
||||
Mode definitions: `.claude/modes/`
|
||||
|
||||
Customize modes by editing these files. Each mode adjusts:
|
||||
- Communication style and verbosity
|
||||
- Output format preferences
|
||||
- Problem-solving approach
|
||||
- When to ask questions vs proceed
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `writing-concisely` — The token-efficient mode activates this skill's patterns
|
||||
- `brainstorming` — The brainstorm mode uses this skill's questioning approach
|
||||
@@ -13,6 +13,7 @@ A design-first reference for REST APIs developers want to use. Standardizes on *
|
||||
- Designing or documenting a new REST API
|
||||
- Generating clients/servers from a spec (FastAPI, Express, NestJS, etc.)
|
||||
- Establishing error, pagination, versioning, or auth conventions for a service
|
||||
- Generating API endpoints, models, and tests from a resource specification
|
||||
- Migrating a spec from OpenAPI 3.0 → 3.1
|
||||
- Setting up lint/governance in CI
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: owasp
|
||||
description: >
|
||||
Use when reviewing code for security vulnerabilities, implementing authentication or authorization flows, handling user input validation, or building web endpoints exposed to untrusted data. Trigger on keywords like XSS, SQL injection, CSRF, input sanitization, password hashing, and security headers. Also apply when auditing existing code for OWASP Top 10 compliance or conducting security-focused code reviews.
|
||||
Use when reviewing code for security vulnerabilities, implementing authentication or authorization flows, handling user input validation, or building web endpoints exposed to untrusted data. Trigger on keywords like XSS, SQL injection, CSRF, input sanitization, password hashing, security headers, "security scan", "vulnerability scan", "npm audit", or "pip-audit". Also apply when auditing existing code for OWASP Top 10 compliance, scanning dependencies for known vulnerabilities, detecting hardcoded secrets, or conducting security-focused code reviews.
|
||||
---
|
||||
|
||||
# OWASP Security Patterns
|
||||
@@ -14,6 +14,8 @@ description: >
|
||||
- Preventing XSS, SQL injection, CSRF, or SSRF
|
||||
- Auditing authentication or authorization flows
|
||||
- Building endpoints that handle untrusted data
|
||||
- Scanning dependencies for known vulnerabilities (`npm audit`, `pip-audit`)
|
||||
- Detecting hardcoded secrets, API keys, or tokens in code
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
|
||||
@@ -0,0 +1,116 @@
|
||||
---
|
||||
name: performance-optimization
|
||||
argument-hint: "[file or function]"
|
||||
description: >
|
||||
Use when analyzing or optimizing code performance — including profiling, benchmarking, fixing N+1 queries, reducing bundle size, eliminating memory leaks, or improving algorithm complexity. Trigger for keywords like "slow", "performance", "optimize", "profiling", "memory leak", "bundle size", "N+1", "re-render", "benchmark", "latency", "throughput", or any request to make code faster. Also activate when investigating production performance issues or when code review flags performance concerns.
|
||||
---
|
||||
|
||||
# Performance Optimization
|
||||
|
||||
## When to Use
|
||||
|
||||
- Profiling slow code to find bottlenecks
|
||||
- Fixing N+1 query problems
|
||||
- Reducing JavaScript bundle size
|
||||
- Eliminating memory leaks
|
||||
- Improving algorithm complexity
|
||||
- Benchmarking before/after optimization
|
||||
- Investigating production latency issues
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
- Premature optimization — profile first, optimize second
|
||||
- Caching strategy design — use `caching`
|
||||
- Database schema/index design — use `databases`
|
||||
- Code structure improvement — use `refactoring`
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Topic | Reference | Key content |
|
||||
|-------|-----------|-------------|
|
||||
| Profiling tools | `references/profiling.md` | Python (cProfile, py-spy, Scalene) and JS/TS (DevTools, Lighthouse, clinic.js) |
|
||||
| Anti-patterns | `references/anti-patterns.md` | N+1 queries, unnecessary re-renders, event loop blocking, memory leaks |
|
||||
|
||||
---
|
||||
|
||||
## Optimization Workflow
|
||||
|
||||
1. **Measure first** — profile to find the actual bottleneck
|
||||
2. **Set a target** — "reduce p95 latency from 500ms to 100ms"
|
||||
3. **Optimize the hot path** — fix the #1 bottleneck, not everything
|
||||
4. **Benchmark before/after** — prove the improvement with numbers
|
||||
5. **Check for regressions** — ensure correctness wasn't sacrificed
|
||||
|
||||
---
|
||||
|
||||
## Profiling Quick Start
|
||||
|
||||
### Python
|
||||
|
||||
```bash
|
||||
# CPU profiling
|
||||
python -m cProfile -o output.prof script.py
|
||||
# Visualize: pip install snakeviz && snakeviz output.prof
|
||||
|
||||
# Live profiling (attach to running process)
|
||||
py-spy top --pid 12345
|
||||
|
||||
# Line-by-line profiling
|
||||
kernprof -lv script.py # requires @profile decorator
|
||||
```
|
||||
|
||||
### JavaScript/TypeScript
|
||||
|
||||
```bash
|
||||
# Bundle analysis
|
||||
npx webpack-bundle-analyzer stats.json
|
||||
# or: ANALYZE=true next build
|
||||
|
||||
# Node.js profiling
|
||||
node --prof app.js
|
||||
clinic doctor -- node app.js
|
||||
|
||||
# Benchmarking
|
||||
npx vitest bench
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Anti-Patterns
|
||||
|
||||
| Anti-Pattern | Detection | Fix |
|
||||
|-------------|-----------|-----|
|
||||
| N+1 queries | `django-debug-toolbar`, `prisma.$on('query')` | `select_related`/`joinedload`/`include` |
|
||||
| Unnecessary re-renders | React DevTools Profiler | `useMemo`, `useCallback`, `React.memo` |
|
||||
| Blocking event loop | `clinic doctor`, high event loop lag | `worker_threads`, async variants |
|
||||
| Memory leaks | Heap snapshots, growing `process.memoryUsage()` | Remove listeners, clear refs, bound caches |
|
||||
| Unbounded lists | No pagination, full table scans | Cursor pagination, `LIMIT` |
|
||||
| Heavy imports | Bundle analyzer showing large deps | Tree-shaking, `import { x }`, code splitting |
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Profile before optimizing** — intuition about bottlenecks is often wrong.
|
||||
2. **Optimize the hot path** — 80% of time is spent in 20% of code.
|
||||
3. **Measure, don't guess** — use benchmarks with statistical significance.
|
||||
4. **Set clear targets** — "faster" is not measurable; "p95 < 100ms" is.
|
||||
5. **Avoid premature optimization** — correctness and readability come first.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
1. **Optimizing cold paths** — spending time on code that runs once.
|
||||
2. **Micro-benchmarking without context** — 10ns vs 20ns doesn't matter if the DB call takes 50ms.
|
||||
3. **Sacrificing readability** — an unreadable optimization is a future bug.
|
||||
4. **Caching without invalidation** — stale data is worse than slow data.
|
||||
5. **Ignoring algorithmic complexity** — no amount of micro-optimization fixes O(n^2) on large inputs.
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `caching` — Caching strategies (memoization, HTTP, Redis, CDN)
|
||||
- `databases` — Query optimization, indexing, connection pooling
|
||||
- `frontend` — React rendering optimization patterns
|
||||
@@ -0,0 +1,115 @@
|
||||
# Performance Anti-Patterns
|
||||
|
||||
## N+1 Queries
|
||||
|
||||
**Signal**: Many small queries instead of one batch query.
|
||||
|
||||
### SQLAlchemy (Python)
|
||||
```python
|
||||
# BAD: N+1 — each user triggers a query for posts
|
||||
users = session.query(User).all()
|
||||
for user in users:
|
||||
print(user.posts) # lazy load, 1 query per user
|
||||
|
||||
# GOOD: eager loading
|
||||
from sqlalchemy.orm import joinedload, selectinload
|
||||
users = session.query(User).options(selectinload(User.posts)).all()
|
||||
```
|
||||
|
||||
### Prisma (TypeScript)
|
||||
```typescript
|
||||
// BAD: N+1
|
||||
const users = await prisma.user.findMany();
|
||||
for (const user of users) {
|
||||
const posts = await prisma.post.findMany({ where: { authorId: user.id } });
|
||||
}
|
||||
|
||||
// GOOD: include
|
||||
const users = await prisma.user.findMany({ include: { posts: true } });
|
||||
```
|
||||
|
||||
### Django
|
||||
```python
|
||||
# BAD
|
||||
for order in Order.objects.all():
|
||||
print(order.customer.name) # N+1
|
||||
|
||||
# GOOD
|
||||
for order in Order.objects.select_related('customer').all():
|
||||
print(order.customer.name) # 1 query with JOIN
|
||||
```
|
||||
|
||||
## Unnecessary Re-renders (React)
|
||||
|
||||
**Signal**: Components re-rendering when their data hasn't changed.
|
||||
|
||||
```typescript
|
||||
// BAD: new object created every render
|
||||
<Child style={{ color: 'red' }} />
|
||||
|
||||
// GOOD: stable reference
|
||||
const style = useMemo(() => ({ color: 'red' }), []);
|
||||
<Child style={style} />
|
||||
|
||||
// BAD: new function every render
|
||||
<Button onClick={() => handleClick(id)} />
|
||||
|
||||
// GOOD: stable callback
|
||||
const handleClick = useCallback(() => doSomething(id), [id]);
|
||||
<Button onClick={handleClick} />
|
||||
```
|
||||
|
||||
Detect with: React DevTools Profiler → "Highlight updates when components render"
|
||||
|
||||
## Blocking the Event Loop (Node.js)
|
||||
|
||||
**Signal**: High event loop lag, slow response times.
|
||||
|
||||
```typescript
|
||||
// BAD: synchronous file read blocks everything
|
||||
const data = fs.readFileSync('large-file.json');
|
||||
|
||||
// GOOD: async
|
||||
const data = await fs.promises.readFile('large-file.json');
|
||||
|
||||
// BAD: CPU-heavy in main thread
|
||||
const hash = crypto.pbkdf2Sync(password, salt, 100000, 64, 'sha512');
|
||||
|
||||
// GOOD: async or worker_threads
|
||||
const hash = await new Promise((resolve, reject) => {
|
||||
crypto.pbkdf2(password, salt, 100000, 64, 'sha512', (err, key) => {
|
||||
err ? reject(err) : resolve(key);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Memory Leaks
|
||||
|
||||
### Python
|
||||
- Circular references with `__del__`
|
||||
- Unclosed file handles / DB connections
|
||||
- Growing global caches without TTL
|
||||
- Detect: `objgraph`, `tracemalloc`
|
||||
|
||||
### JavaScript
|
||||
- Detached DOM nodes
|
||||
- Forgotten event listeners (`addEventListener` without `removeEventListener`)
|
||||
- Closures capturing large scopes
|
||||
- Unbounded `Map`/`Set` growth
|
||||
- Detect: Chrome Heap Snapshots, `process.memoryUsage()`
|
||||
|
||||
## Heavy Imports / Bundle Bloat
|
||||
|
||||
```typescript
|
||||
// BAD: imports entire library
|
||||
import _ from 'lodash';
|
||||
|
||||
// GOOD: tree-shakeable import
|
||||
import { debounce } from 'lodash-es';
|
||||
|
||||
// GOOD: native alternative
|
||||
const debounce = (fn, ms) => { /* 5 lines */ };
|
||||
```
|
||||
|
||||
Replace heavy deps: moment → dayjs, lodash → lodash-es or native, date-fns (tree-shakeable).
|
||||
Use `React.lazy()` + `Suspense` for route-based code splitting.
|
||||
@@ -0,0 +1,109 @@
|
||||
# Profiling Tools Reference
|
||||
|
||||
## Python
|
||||
|
||||
### cProfile (built-in, function-level)
|
||||
```bash
|
||||
python -m cProfile -o output.prof script.py
|
||||
# Visualize
|
||||
pip install snakeviz && snakeviz output.prof
|
||||
```
|
||||
|
||||
### py-spy (sampling, production-safe)
|
||||
```bash
|
||||
# Top-like view of running process
|
||||
py-spy top --pid 12345
|
||||
|
||||
# Generate flame graph
|
||||
py-spy record -o profile.svg --pid 12345
|
||||
```
|
||||
|
||||
### line_profiler (line-by-line)
|
||||
```bash
|
||||
# Add @profile decorator to target function
|
||||
kernprof -lv script.py
|
||||
```
|
||||
|
||||
### memory_profiler (memory usage)
|
||||
```bash
|
||||
# Add @profile decorator
|
||||
python -m memory_profiler script.py
|
||||
|
||||
# Or use stdlib tracemalloc for snapshot comparison
|
||||
```
|
||||
|
||||
### Scalene (CPU + memory + GPU)
|
||||
```bash
|
||||
scalene script.py
|
||||
# Modern alternative, AI-suggested optimizations
|
||||
```
|
||||
|
||||
## JavaScript / TypeScript
|
||||
|
||||
### Chrome DevTools Performance
|
||||
- Performance tab → Record → interact → Stop
|
||||
- Flame chart shows main thread activity
|
||||
- Look for long tasks (>50ms), layout thrashing
|
||||
|
||||
### Lighthouse (web vitals)
|
||||
```bash
|
||||
npx lighthouse https://localhost:3000 --output=json
|
||||
# CI integration
|
||||
npx @lhci/cli autorun
|
||||
```
|
||||
|
||||
### Bundle Analysis
|
||||
```bash
|
||||
# Webpack
|
||||
npx webpack-bundle-analyzer stats.json
|
||||
|
||||
# Next.js
|
||||
ANALYZE=true next build
|
||||
|
||||
# Source map explorer
|
||||
npx source-map-explorer dist/**/*.js
|
||||
```
|
||||
|
||||
### clinic.js (Node.js)
|
||||
```bash
|
||||
# Event loop health
|
||||
clinic doctor -- node app.js
|
||||
|
||||
# CPU flame graph
|
||||
clinic flame -- node app.js
|
||||
|
||||
# Async bottlenecks
|
||||
clinic bubbleprof -- node app.js
|
||||
```
|
||||
|
||||
### Node.js built-in
|
||||
```bash
|
||||
node --prof app.js
|
||||
node --prof-process isolate-*.log > profile.txt
|
||||
```
|
||||
|
||||
## Benchmarking
|
||||
|
||||
### Python
|
||||
```bash
|
||||
# pytest-benchmark
|
||||
pytest --benchmark-only
|
||||
|
||||
# timeit
|
||||
python -m timeit -s "setup" "expression"
|
||||
```
|
||||
|
||||
### JavaScript/TypeScript
|
||||
```typescript
|
||||
// Vitest bench (built-in)
|
||||
// my-func.bench.ts
|
||||
import { bench } from 'vitest';
|
||||
|
||||
bench('my function', () => {
|
||||
myFunction(testData);
|
||||
});
|
||||
```
|
||||
|
||||
```bash
|
||||
npx vitest bench
|
||||
```
|
||||
@@ -0,0 +1,113 @@
|
||||
---
|
||||
name: refactoring
|
||||
argument-hint: "[file or function]"
|
||||
description: >
|
||||
Use when improving code structure, readability, or maintainability without changing behavior. Trigger for keywords like "refactor", "clean up", "extract", "simplify", "rename", "restructure", "code smell", "technical debt", "DRY", or any request to improve code quality without adding features. Also activate when code reviews identify structural issues, when functions are too long, or when duplication needs elimination.
|
||||
---
|
||||
|
||||
# Refactoring
|
||||
|
||||
## When to Use
|
||||
|
||||
- Improving code structure without changing behavior
|
||||
- Extracting reusable functions or components
|
||||
- Eliminating code duplication
|
||||
- Reducing complexity (long functions, deep nesting)
|
||||
- Renaming for clarity
|
||||
- Addressing code review feedback about structure
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
- Adding new features — use `feature-workflow`
|
||||
- Fixing bugs — use `systematic-debugging` (behavior change, not refactoring)
|
||||
- Performance optimization — use `performance-optimization`
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Topic | Reference | Key content |
|
||||
|-------|-----------|-------------|
|
||||
| Refactoring patterns | `references/patterns.md` | Extract, inline, rename, move, decompose, introduce parameter object |
|
||||
| Code smells | `references/code-smells.md` | Detection signals and recommended refactorings |
|
||||
|
||||
---
|
||||
|
||||
## Safe Refactoring Workflow
|
||||
|
||||
1. **Ensure tests pass** before any change
|
||||
2. **Make one small, behavior-preserving change** at a time
|
||||
3. **Run tests after each change**
|
||||
4. **Commit each successful step** independently
|
||||
5. **Use type checkers** (mypy/tsc) as a secondary safety net
|
||||
6. **Never mix refactoring with feature/bug changes** in the same commit
|
||||
|
||||
---
|
||||
|
||||
## Core Patterns
|
||||
|
||||
| Pattern | When | Example |
|
||||
|---------|------|---------|
|
||||
| Extract function | Long function, repeated logic | Pull 10-line block into named function |
|
||||
| Inline function | Trivial wrapper adding no clarity | Remove `getAge()` that just returns `this.age` |
|
||||
| Rename symbol | Name doesn't reveal intent | `x` → `userCount` |
|
||||
| Introduce parameter object | 4+ related parameters | `(name, email, age)` → `UserInput` |
|
||||
| Replace conditional with polymorphism | Long if/else or switch chains | Strategy pattern or subclass dispatch |
|
||||
| Decompose conditional | Complex boolean expression | `isEligible()` instead of `age > 18 && !banned && verified` |
|
||||
| Extract variable | Complex expression | `const isOverBudget = total > limit * 1.1` |
|
||||
|
||||
---
|
||||
|
||||
## Code Smell Signals
|
||||
|
||||
- **Long function** (>20-30 lines)
|
||||
- **Long parameter list** (>3-4 params)
|
||||
- **Duplicated logic** across multiple locations
|
||||
- **Deep nesting** (>3 levels)
|
||||
- **Feature envy** — function uses another class's data more than its own
|
||||
- **Shotgun surgery** — one change requires edits in many files
|
||||
- **Primitive obsession** — raw strings/dicts instead of typed objects
|
||||
- **Dead code** — unreachable or unused functions/imports
|
||||
|
||||
---
|
||||
|
||||
## Python-Specific
|
||||
|
||||
- Convert `dict` bags to **dataclasses** or **TypedDict**
|
||||
- Add **type hints** progressively
|
||||
- Replace loops with **comprehensions** where clearer
|
||||
- Use **`@property`** instead of get/set methods
|
||||
- Use **`Enum`** instead of string constants
|
||||
|
||||
## TypeScript-Specific
|
||||
|
||||
- Use **discriminated unions** instead of class hierarchies
|
||||
- Replace `any` with **generics** or **`unknown`** + narrowing
|
||||
- Replace enums with **`as const`** objects for tree-shaking
|
||||
- Extract **utility types** (`Pick`, `Omit`, `Partial`)
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Rule of three** — extract on the third duplication, not the first.
|
||||
2. **Tests are the safety net** — never refactor without them.
|
||||
3. **Small steps** — one rename is better than a big-bang rewrite.
|
||||
4. **Preserve interfaces** — change internals, not public APIs (unless that's the goal).
|
||||
5. **Use IDE tooling** — automated rename/move updates all references.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
1. **Refactoring without tests** — no safety net to catch regressions.
|
||||
2. **Mixing refactoring with features** — makes it impossible to identify behavior changes.
|
||||
3. **Premature abstraction** — extracting patterns before duplication exists.
|
||||
4. **Too-large refactors** — big-bang rewrites instead of incremental steps.
|
||||
5. **Breaking public interfaces** — changing signatures without updating callers.
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `testing` — Ensure test coverage before refactoring
|
||||
- `languages` — Language-specific idioms and patterns
|
||||
- `writing-concisely` — Refactoring responses can be terse (show before/after)
|
||||
@@ -0,0 +1,32 @@
|
||||
# Code Smells Detection Guide
|
||||
|
||||
## Smell → Refactoring Map
|
||||
|
||||
| Smell | Signal | Refactoring |
|
||||
|-------|--------|-------------|
|
||||
| Long function | >20-30 lines | Extract function |
|
||||
| Long parameter list | >3-4 params | Introduce parameter object |
|
||||
| Duplicated logic | Same code in 3+ places | Extract function, DRY |
|
||||
| Deep nesting | >3 levels of indentation | Early return, extract function |
|
||||
| Feature envy | Uses another class's data more than its own | Move method to the class with the data |
|
||||
| Shotgun surgery | One change → edits in many files | Move related code together |
|
||||
| Primitive obsession | Raw strings/dicts instead of types | Introduce dataclass/interface |
|
||||
| Dead code | Unreachable or unused | Delete it (git has history) |
|
||||
| God class | Class does too many things | Extract class by responsibility |
|
||||
| Comments as deodorant | Comments explaining messy code | Refactor the code to be clear |
|
||||
|
||||
## Python-Specific Smells
|
||||
|
||||
- `dict` used as a struct → use `@dataclass` or `TypedDict`
|
||||
- Missing type hints on public functions
|
||||
- Manual `__init__` boilerplate → `@dataclass`
|
||||
- String constants → `Enum`
|
||||
- Getter/setter methods → `@property`
|
||||
|
||||
## TypeScript-Specific Smells
|
||||
|
||||
- `any` type → `unknown` + narrowing or generics
|
||||
- Enum → `as const` object (better tree-shaking)
|
||||
- Class hierarchy for variants → discriminated union
|
||||
- Interface duplication → utility types (`Pick`, `Omit`, `Partial`)
|
||||
- Index as key in lists → stable unique ID
|
||||
@@ -0,0 +1,93 @@
|
||||
# Refactoring Patterns
|
||||
|
||||
## Extract Function
|
||||
|
||||
Pull cohesive logic into a named function.
|
||||
|
||||
```python
|
||||
# Before
|
||||
def process_order(order):
|
||||
# validate
|
||||
if not order.items:
|
||||
raise ValueError("Empty order")
|
||||
if order.total < 0:
|
||||
raise ValueError("Negative total")
|
||||
# ... 50 more lines
|
||||
|
||||
# After
|
||||
def validate_order(order):
|
||||
if not order.items:
|
||||
raise ValueError("Empty order")
|
||||
if order.total < 0:
|
||||
raise ValueError("Negative total")
|
||||
|
||||
def process_order(order):
|
||||
validate_order(order)
|
||||
# ... rest of processing
|
||||
```
|
||||
|
||||
## Introduce Parameter Object
|
||||
|
||||
Group 4+ related parameters into a single object.
|
||||
|
||||
```typescript
|
||||
// Before
|
||||
function createUser(name: string, email: string, age: number, role: string) { ... }
|
||||
|
||||
// After
|
||||
interface CreateUserInput {
|
||||
name: string;
|
||||
email: string;
|
||||
age: number;
|
||||
role: string;
|
||||
}
|
||||
function createUser(input: CreateUserInput) { ... }
|
||||
```
|
||||
|
||||
## Replace Conditional with Polymorphism
|
||||
|
||||
```typescript
|
||||
// Before
|
||||
function getPrice(type: string, base: number): number {
|
||||
if (type === 'premium') return base * 0.8;
|
||||
if (type === 'bulk') return base * 0.7;
|
||||
return base;
|
||||
}
|
||||
|
||||
// After
|
||||
const pricingStrategies: Record<string, (base: number) => number> = {
|
||||
premium: (base) => base * 0.8,
|
||||
bulk: (base) => base * 0.7,
|
||||
standard: (base) => base,
|
||||
};
|
||||
function getPrice(type: string, base: number): number {
|
||||
return (pricingStrategies[type] ?? pricingStrategies.standard)(base);
|
||||
}
|
||||
```
|
||||
|
||||
## Decompose Conditional
|
||||
|
||||
```python
|
||||
# Before
|
||||
if age > 18 and not banned and verified and subscription_active:
|
||||
grant_access()
|
||||
|
||||
# After
|
||||
def is_eligible(user):
|
||||
return user.age > 18 and not user.banned and user.verified and user.subscription_active
|
||||
|
||||
if is_eligible(user):
|
||||
grant_access()
|
||||
```
|
||||
|
||||
## Extract Variable
|
||||
|
||||
```typescript
|
||||
// Before
|
||||
if (order.total > 100 && order.items.length > 5 && !order.hasDiscount) { ... }
|
||||
|
||||
// After
|
||||
const isLargeOrder = order.total > 100 && order.items.length > 5;
|
||||
const qualifiesForDiscount = isLargeOrder && !order.hasDiscount;
|
||||
if (qualifiesForDiscount) { ... }
|
||||
```
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
name: root-cause-tracing
|
||||
user-invocable: false
|
||||
description: >
|
||||
Use when a bug manifests far from its origin, when stack traces show multiple layers of indirection, or when data corruption appears with no obvious source. Use for any scenario involving "it was already wrong by the time it got here," deep execution stack errors, constraint violations caused by upstream failures, or mysterious data state issues. Always prefer this over surface-level fixes when the error location differs from the bug location.
|
||||
---
|
||||
|
||||
@@ -0,0 +1,123 @@
|
||||
---
|
||||
name: session-management
|
||||
argument-hint: "[save/list/restore/index/load/status]"
|
||||
description: >
|
||||
Use when managing session state — including saving/restoring checkpoints, generating project structure indexes, loading project components into context, or checking project status. Trigger for keywords like "checkpoint", "save state", "restore", "index", "project structure", "load context", "status", "what's the state", or any request to manage the working session. Also activate when resuming work from a previous session or when needing to understand the current project layout.
|
||||
---
|
||||
|
||||
# Session Management
|
||||
|
||||
## When to Use
|
||||
|
||||
- Saving or restoring session state (checkpoints)
|
||||
- Generating project structure indexes
|
||||
- Loading specific project components into context
|
||||
- Checking current project status (git, tasks, PRs)
|
||||
- Resuming work from a previous session
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
- Git operations (commit, push, PR) — use `git-workflows`
|
||||
- Branch management — use `using-git-worktrees`
|
||||
- Launching parallel background work — use `dispatching-parallel-agents`
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Topic | Reference | Key content |
|
||||
|-------|-----------|-------------|
|
||||
| Checkpoints | `references/checkpoints.md` | Save/restore/list/delete session state |
|
||||
| Project indexing | `references/indexing.md` | Generate PROJECT_INDEX.md, scan structure |
|
||||
| Context loading | `references/loading.md` | Load components by category or path |
|
||||
| Status checking | `references/status.md` | Git state, tasks, recent activity |
|
||||
|
||||
---
|
||||
|
||||
## Checkpoints
|
||||
|
||||
Save and restore conversation context using git-based state:
|
||||
|
||||
```bash
|
||||
# Save current state
|
||||
# → creates git stash + metadata in .claude/checkpoints/
|
||||
/checkpoint save feature-auth
|
||||
|
||||
# List available checkpoints
|
||||
/checkpoint list
|
||||
|
||||
# Restore a checkpoint
|
||||
/checkpoint restore feature-auth
|
||||
|
||||
# Delete old checkpoint
|
||||
/checkpoint delete old-checkpoint
|
||||
```
|
||||
|
||||
Auto-checkpoint is suggested before major refactoring, context switches, and risky operations.
|
||||
|
||||
---
|
||||
|
||||
## Project Indexing
|
||||
|
||||
Generate a comprehensive project structure index:
|
||||
|
||||
```bash
|
||||
# Generate PROJECT_INDEX.md
|
||||
/index
|
||||
|
||||
# Shallow index (3 levels deep)
|
||||
/index --depth=3
|
||||
```
|
||||
|
||||
The index categorizes files by type: entry points, API routes, models, services, utilities, tests, and configuration.
|
||||
|
||||
---
|
||||
|
||||
## Context Loading
|
||||
|
||||
Load specific components into context for focused work:
|
||||
|
||||
| Category | What It Loads |
|
||||
|----------|---------------|
|
||||
| `api` | API routes and endpoints |
|
||||
| `models` | Data models and types |
|
||||
| `services` | Business logic services |
|
||||
| `auth` | Authentication related |
|
||||
| `db` | Database related |
|
||||
| `tests` | Test files |
|
||||
| `config` | Configuration files |
|
||||
|
||||
```bash
|
||||
/load api # Load all API routes
|
||||
/load src/services/user.ts # Load specific file
|
||||
/load auth --related # Load auth + related files
|
||||
/load --all --shallow # Quick overview of everything
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
Get current project status:
|
||||
|
||||
```bash
|
||||
/status
|
||||
```
|
||||
|
||||
Shows: git branch and status, in-progress/pending/completed tasks, recent commits, open PRs.
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Checkpoint before context switches** — save state when switching tasks.
|
||||
2. **Index periodically** — regenerate when project structure changes significantly.
|
||||
3. **Load narrow, expand as needed** — start with specific components, add related files.
|
||||
4. **Name checkpoints descriptively** — `auth-progress` beats `checkpoint-1`.
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `using-git-worktrees` — Isolated branch management for parallel work
|
||||
- `dispatching-parallel-agents` — Launching parallel background tasks
|
||||
@@ -0,0 +1,48 @@
|
||||
# Checkpoints
|
||||
|
||||
## Save Checkpoint
|
||||
|
||||
```bash
|
||||
/checkpoint save [name]
|
||||
```
|
||||
|
||||
Creates a git stash with metadata in `.claude/checkpoints/[name].json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "feature-auth",
|
||||
"created": "2026-04-19T14:30:00Z",
|
||||
"git_stash": "stash@{0}",
|
||||
"files_in_context": ["src/auth/login.ts", "src/auth/token.ts"],
|
||||
"current_task": "Implementing JWT refresh",
|
||||
"notes": "User-provided notes"
|
||||
}
|
||||
```
|
||||
|
||||
## List Checkpoints
|
||||
|
||||
```bash
|
||||
/checkpoint list
|
||||
```
|
||||
|
||||
## Restore Checkpoint
|
||||
|
||||
```bash
|
||||
/checkpoint restore [name]
|
||||
```
|
||||
|
||||
Applies git stash, loads metadata, summarizes restored context.
|
||||
|
||||
## Delete Checkpoint
|
||||
|
||||
```bash
|
||||
/checkpoint delete [name]
|
||||
```
|
||||
|
||||
## Auto-Checkpoint Triggers
|
||||
|
||||
Suggest checkpoints before:
|
||||
- Major refactoring
|
||||
- Context switches
|
||||
- Risky operations
|
||||
- Natural breakpoints in complex work
|
||||
@@ -0,0 +1,45 @@
|
||||
# Project Indexing
|
||||
|
||||
## Generate Index
|
||||
|
||||
Scan the project and create `PROJECT_INDEX.md`:
|
||||
|
||||
### Excluded Directories
|
||||
`node_modules/`, `.git/`, `__pycache__/`, `dist/`, `build/`, `.next/`, `venv/`, `.venv/`, coverage, cache
|
||||
|
||||
### File Categories
|
||||
- **Entry Points**: Main files, index files, app entry
|
||||
- **API/Routes**: Endpoint definitions
|
||||
- **Models/Types**: Data structures, schemas
|
||||
- **Services**: Business logic
|
||||
- **Utilities**: Helper functions
|
||||
- **Tests**: Test files
|
||||
- **Configuration**: Config files, env templates
|
||||
|
||||
### Output Format
|
||||
|
||||
```markdown
|
||||
# Project Index: [Name]
|
||||
|
||||
Generated: [timestamp]
|
||||
|
||||
## Quick Navigation
|
||||
| Category | Key Files |
|
||||
|----------|-----------|
|
||||
| Entry Points | [list] |
|
||||
| API Routes | [list] |
|
||||
|
||||
## Directory Structure
|
||||
[tree view]
|
||||
|
||||
## Key Files
|
||||
### Entry Points
|
||||
- `[path]` - [description]
|
||||
|
||||
## Dependencies
|
||||
### External
|
||||
- [package]: [purpose]
|
||||
|
||||
## Architecture Notes
|
||||
[patterns observed]
|
||||
```
|
||||
@@ -0,0 +1,49 @@
|
||||
# Context Loading
|
||||
|
||||
## Load Components
|
||||
|
||||
Load specific parts of the project into context for focused work.
|
||||
|
||||
### By Category
|
||||
|
||||
| Category | What It Loads |
|
||||
|----------|---------------|
|
||||
| `api` | API routes and endpoints |
|
||||
| `models` | Data models and types |
|
||||
| `services` | Business logic services |
|
||||
| `utils` | Utility functions |
|
||||
| `tests` | Test files |
|
||||
| `config` | Configuration files |
|
||||
| `auth` | Authentication related |
|
||||
| `db` | Database related |
|
||||
|
||||
### By Path
|
||||
|
||||
```bash
|
||||
/load src/services/user.ts # Specific file
|
||||
/load src/auth/ # Directory
|
||||
```
|
||||
|
||||
### Flags
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--all` | Load all key components |
|
||||
| `--shallow` | Load only file summaries |
|
||||
| `--deep` | Load full file contents |
|
||||
| `--related` | Include related files |
|
||||
|
||||
### Output
|
||||
|
||||
```markdown
|
||||
## Loaded Context
|
||||
|
||||
### Files Loaded (N)
|
||||
- `path/to/file.ts` - [purpose]
|
||||
|
||||
### Key Components
|
||||
- [Component]: [description]
|
||||
|
||||
### Ready For
|
||||
- [suggested actions based on loaded context]
|
||||
```
|
||||
@@ -0,0 +1,34 @@
|
||||
# Status Checking
|
||||
|
||||
## Project Status
|
||||
|
||||
Show current project state:
|
||||
|
||||
```bash
|
||||
git status
|
||||
git log --oneline -5
|
||||
```
|
||||
|
||||
### Output Format
|
||||
|
||||
```markdown
|
||||
## Project Status
|
||||
|
||||
### Git
|
||||
- Branch: `feature/xyz`
|
||||
- Status: Clean / X modified files
|
||||
|
||||
### Tasks
|
||||
- In Progress: X
|
||||
- Pending: Y
|
||||
- Completed: Z
|
||||
|
||||
### Recent Commits
|
||||
1. [commit message]
|
||||
2. [commit message]
|
||||
|
||||
### Open PRs
|
||||
- #123: [title]
|
||||
```
|
||||
|
||||
Combines git state, TodoWrite tasks, and recent activity into a single snapshot.
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
name: testing-anti-patterns
|
||||
user-invocable: false
|
||||
description: >
|
||||
Use when writing, reviewing, or debugging tests. Activate for keywords like "mock", "stub", "test helper", "flaky test", "test passes but bug ships", "false positive", "test coverage", or when tests seem unreliable. Also trigger when reviewing test code in PRs, when tests pass but production breaks, when someone proposes heavy mocking, or when test failures are intermittent. If any test smells wrong or feels like it is not actually verifying real behavior, this skill applies.
|
||||
---
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
name: writing-concisely
|
||||
user-invocable: false
|
||||
description: >
|
||||
Use this skill when optimizing token usage, reducing response verbosity, or working in high-volume development sessions. Trigger for any mention of token savings, cost optimization, concise output, compressed responses, or the --format=concise/ultra flags. Also applies during repetitive tasks, quick iterations, simple clear requests, or when the user activates token-efficient mode. This is a cross-cutting optimization that applies to all other skills.
|
||||
---
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
name: writing-plans
|
||||
argument-hint: "[task description]"
|
||||
description: >
|
||||
Use when a multi-step implementation task needs to be broken down before coding begins. Activate for keywords like "plan", "break down", "implementation steps", "task list", "how to implement", "write a plan", or when a feature spans multiple files or components. Also trigger when handing off work to another developer, when the user says "let's plan this out", or when a task is complex enough that jumping straight to code would be risky. If in doubt, plan first.
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user