diff --git a/CHANGELOG.md b/CHANGELOG.md index b269064..de71b60 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,21 +6,67 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] +## [1.2.0] - 2025-01-10 + ### Added -- `examples/` folder with 18 ready-to-use templates - - 4 agent templates (code-reviewer, test-writer, security-auditor, refactoring-specialist) - - 2 skill templates (tdd-workflow, security-checklist) - - 3 command templates (commit, review-pr, generate-tests) - - 4 hook templates (bash + PowerShell for security-check, auto-format) - - 3 config templates (settings.json, mcp.json, .gitignore-claude) - - 2 memory templates (project + personal CLAUDE.md) -- `CONTRIBUTING.md` with contribution guidelines -- `CHANGELOG.md` (this file) -- Learning Paths section in README for different audience profiles -- **OpusPlan Mode** documentation in Plan Mode section - - Uses Opus for planning, Sonnet for implementation - - Cost optimization for Pro users with limited Opus tokens - - Alternative approach using subagents with specific models +- **Section 1.6: Migration Patterns** (~230 lines) + - Complete guide for transitioning from GitHub Copilot to Claude Code + - Cursor to Claude Code migration strategies + - Hybrid workflow recommendations (when to use which tool) + - Week-by-week migration checklist + - Common migration issues and solutions + - Success metrics and productivity indicators +- **Section 2.2: Cost Awareness & Optimization** (~220 lines) + - Detailed pricing model breakdown (Sonnet/Opus/Haiku) + - Cost optimization strategies (5 actionable patterns) + - Real-world cost examples and ROI calculations + - Budget tracking and cost-conscious workflows + - Cost vs. value analysis (when to optimize, when not to) + - Red flags for cost waste indicators +- **Section 9.3: Release Notes Generation** (~280 lines) + - Command-based release notes automation + - CI/CD integration for automated changelog + - Interactive workflow for manual control + - Three output formats (CHANGELOG.md, GitHub Release, User Announcement) + - Best practices and common issues + - Complete examples with real commit history +- **Section 10.4: Enhanced Troubleshooting** (~170 lines added) + - MCP server connection issues (Serena, Context7, Sequential) + - Permission pattern matching problems + - Timeout handling strategies + - Platform-specific installation issues (Windows, macOS, Linux) +- **Appendix A.10: Emergency Hotfix Checklist** (~140 lines) + - Step-by-step hotfix protocol (8 phases) + - Time-based decision matrix (<5 min to >30 min) + - Claude Code hotfix-specific commands + - Hotfix anti-patterns and best practices + - Communication templates for incident updates +- **Appendix A.11: Git Archaeology Pattern** (~250 lines) + - 6 archaeology patterns (mysterious code, feature evolution, bug introduction) + - Claude-optimized git commands for investigation + - Real-world examples (workarounds, breaking changes, dead code) + - Archaeology prompt template + - Finding domain experts via git history +- Enhanced Windows disclaimer in README (more visible, actionable) +- Updated `claude-setup-audit-prompt.md` with new checklist items + - Cost Awareness evaluation criteria + - Migration Patterns assessment + - Release Notes automation check + - Emergency procedures documentation + - Git archaeology usage patterns + +### Changed +- Improved Windows support visibility in README + - Changed from small note to prominent callout box + - Added specific areas of concern (PowerShell, paths, batch files) + - Clear call-to-action for Windows contributors + - Status indicator for platform support + +### Stats +- Guide expanded from ~4955 lines to ~6250 lines (~26% growth) +- Added ~1300 lines of high-value, practical content +- 6 major new sections addressing real-world developer needs +- Focus on cost optimization, migration, and production scenarios ## [1.1.0] - 2025-01-10 diff --git a/README.md b/README.md index e14575b..196271f 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,22 @@ A significant source of inspiration for this work was [Claudelog.com](https://cl **Important note**: This guide was largely generated with the help of AI. As such, it likely contains errors, inaccuracies, or outdated information. I would be delighted to receive any feedback, corrections, or — even better — pull requests to improve it. Don't hesitate to [open an issue](../../issues) or submit a PR! -**Windows disclaimer**: I work on macOS and have not tested the Windows-specific commands (PowerShell, batch files, paths). Windows instructions were generated with AI assistance. If you encounter issues, please open an issue or PR — contributions from Windows users are especially welcome! +> **⚠️ WINDOWS USERS - IMPORTANT DISCLAIMER** +> +> I work on macOS and **have not personally tested Windows-specific commands** (PowerShell, batch files, path syntax). +> +> **What this means for you:** +> - PowerShell scripts are AI-generated and may need adjustment +> - Path separators (`\` vs `/`) may be incorrect in some examples +> - Batch file hooks may require debugging +> - Git Bash commands should work as-is (they use Unix syntax) +> +> **How you can help:** +> 1. [Open an issue](../../issues) if you find Windows-specific problems +> 2. Submit a PR with corrections (Windows testers highly appreciated!) +> 3. Join our [community discussions](../../discussions) to share Windows-specific tips +> +> **Status**: We are actively seeking Windows contributors to improve platform support. **Language**: I wrote this guide in English by default to reach a wider audience, but French is my native language. I could easily translate it to French myself, or leverage AI and community contributions for other languages. Let me know if translations would be useful! diff --git a/claude-setup-audit-prompt.md b/claude-setup-audit-prompt.md index 4fef718..52da6bc 100644 --- a/claude-setup-audit-prompt.md +++ b/claude-setup-audit-prompt.md @@ -197,6 +197,32 @@ For each category, evaluate against these criteria: - [ ] Meta-rules for fixing system, not just code - [ ] Learning from repeated issues +**Cost Awareness (Guide Section 2.2)** +- [ ] Understanding of pricing model (Sonnet/Opus/Haiku costs) +- [ ] Using /compact proactively to manage costs +- [ ] Being specific in queries to reduce token usage +- [ ] Tracking costs via Anthropic Console + +**Migration Patterns (Guide Section 1.6)** +- [ ] Understanding differences vs Copilot/Cursor +- [ ] Hybrid workflow defined (when to use which tool) +- [ ] Successfully transitioned from previous AI tools + +**Release Notes Automation (Guide Section 9.3)** +- [ ] Using Claude for changelog generation +- [ ] Automated release notes in CI/CD +- [ ] User-facing vs technical release notes + +**Emergency Procedures (Guide Appendix A.10)** +- [ ] Hotfix checklist available for production issues +- [ ] Plan Mode usage during critical fixes +- [ ] Post-mortem process documented + +**Git Archaeology (Guide Appendix A.11)** +- [ ] Using git blame/log for code understanding +- [ ] Finding domain experts via git history +- [ ] Understanding code evolution patterns + #### 2.2 Calculate Health Score **Formula**: `Score = (earned_points / max_points) × 100`