From 162b8562cff1382e2c81bed380982f6eb963f49c Mon Sep 17 00:00:00 2001 From: Florian BRUNIAUX Date: Sat, 10 Jan 2026 17:55:46 +0100 Subject: [PATCH] docs: release v2.3.0 with DeepTo guide integration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add DeepTo Claude Code Guide reference to Resources section - Document all DeepTo additions in CHANGELOG: • Image processing (direct terminal input) • Session continuation/resume (--continue, --resume) • XML-structured prompts (semantic tags) • ccusage CLI tool (cost analytics) • Unix piping workflows (automation patterns) - Update version to 2.3 across all documentation - Include proper source attribution throughout Co-Authored-By: Claude Sonnet 4.5 --- CHANGELOG.md | 108 +++ README.md | 8 +- english-ultimate-claude-code-guide.md | 864 +++++++++++++++++++- examples/memory/CLAUDE.md.personal-template | 1 - 4 files changed, 975 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c558935..19c7659 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,114 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] +## [2.3.0] - 2026-01-10 + +### Added +- **DeepTo Claude Code Guide integration** (~800 lines across 5 sections) + - **Image Processing** (Section 2.3.2, lines 377-445) + - Direct image input via paste/drag-drop in terminal + - Screenshot analysis, UI debugging, error message analysis + - Best practices for image-based workflows + - Supported formats: PNG, JPG, GIF, WebP, screenshots + - **Session Continuation and Resume** (Section 2.3.4, lines 447-560) + - `claude --continue` / `-c` to resume last session + - `claude --resume ` / `-r ` for specific sessions + - Use cases table: long-term projects, research, interrupted work, daily workflows + - Context preservation across terminal sessions + - Integration with MCP Serena for persistent memory + - **XML-Structured Prompts** (Section 2.6, lines 1582-2148) + - Semantic organization using ``, ``, ``, ``, `` tags + - Benefits table: disambiguation, role clarity, example isolation, constraint definition + - 3 practical examples: code review, feature implementation, bug investigation + - Advanced patterns: nested tags, multiple examples, conditional instructions + - Integration with CLAUDE.md and Plan Mode + - Template library for common scenarios + - **ccusage CLI Tool** (Section 3.5.3, around line 970) + - Detailed cost analytics and tracking + - Model-specific breakdowns (Haiku/Sonnet/Opus) + - Token usage analysis and optimization insights + - Installation and usage instructions + - **Unix Piping Workflows** (Section 9.3.3, line 4490) + - Feeding content to Claude via stdin pipes + - Output format options (text, json, markdown) + - Build script integration patterns + - CI/CD pipeline examples (linting, testing, security) + - Automated analysis and report generation + - **DeepTo Guide reference** added to README.md Resources section + - Listed alongside zebbern, Claudelog, and ykdojo guides + - Brief description covering all integrated concepts + - **Source attribution** included in all new sections + - Proper credit to https://cc.deeptoai.com/docs/en/best-practices/claude-code-comprehensive-guide + - Following same attribution format used for other community guides + +### Changed +- **Guide statistics updated** + - Guide expanded to approximately 9,700+ lines (+800 lines from DeepTo integration) + - Enhanced coverage of context management, structured prompting, and automation +- **README.md Resources section enhanced** + - Added DeepTo Claude Code Guide to Related Guides + +### Stats +- 0 new files created (documentation enhancement only) +- 3 files modified (README.md, english-ultimate-claude-code-guide.md, CHANGELOG.md) +- Focus on advanced prompting techniques, cost optimization, and automation workflows +- Integration of community best practices from DeepTo guide + +## [2.2.0] - 2026-01-10 + +### Added +- **ykdojo/claude-code-tips reference integration** (~300 lines, 6 tips) + - Added to References section in README.md (2 locations: Key inspirations + Related Guides) + - Added to Learning Sites table in guide (Section 10.3.3, lines 8277, 8500) + - Listed as peer guide alongside Claudelog and zebbern + - **Tip 1: Undocumented Commands** integrated in Section 10.1 Commands Table + - `/usage` - Check rate limits and token allocation + - `/stats` - View usage statistics with activity graphs + - `/chrome` - Toggle native browser integration + - `/mcp` - Manage Model Context Protocol servers + - **Tips 3+4+8: Keyboard Shortcuts** integrated in Section 10.2 + - Restructured with 2 categories: "Session Control" + "Input & Navigation" + - `Ctrl+A` - Jump to beginning of line + - `Ctrl+E` - Jump to end of line + - `Ctrl+W` - Delete previous word + - `Ctrl+G` - Open external editor for long text + - `Ctrl+B` - Run command in background + - **Tip 5: Session Handoff Pattern** new subsection in Section 2.2 (lines 1252-1308) + - Complete template with 5 sections (Accomplished, Current State, Decisions, Next Steps, Context) + - When-to-use table with 5 scenarios (end of day, context limit, switching focus, interruption, debugging) + - Storage location: `claudedocs/handoffs/handoff-YYYY-MM-DD.md` + - Pro tip: Ask Claude to generate handoff automatically + - **Tip 12: GitHub Actions CLI Debugging** new subsection in Section 9.3 (lines 4445-4500) + - Quick investigation workflow with `gh run` commands + - Common commands table: list, view, view logs, watch, rerun + - Practical example combining `gh` with Claude Code + - Pro tip: Pipe failed logs directly to Claude for analysis + - **Additional topics worth exploring** section added (lines 8516-8522) + - 6 non-integrated but pertinent topics from ykdojo listed + - Voice transcription workflows (superwhisper/MacWhisper) + - Tmux for autonomous testing + - cc-safe security tool + - Cascade multitasking method + - Container experimentation with Docker + - Half-clone technique for context trimming + +### Changed +- **Guide statistics updated** + - Guide expanded from 8,505 to 8,929 lines (+424 lines, +5.0%) + - Word count increased from ~31,280 to 33,219 words (+1,939 words, +6.2%) + - Reading time updated: "~3 hours" → "~2h15min" (more precise estimate) +- **Version alignment** across documentation + - english-ultimate-claude-code-guide.md: Version 2.1 → 2.2 + - README.md: Version 2.1 → 2.2 + - CHANGELOG.md: New release 2.2.0 documented + +### Stats +- 0 new files created (documentation enhancement only) +- 3 files modified (README.md, english-ultimate-claude-code-guide.md, CHANGELOG.md) +- Guide grew by 424 lines (5.0% growth from v2.1.0) +- Focus on productivity techniques and terminal efficiency +- Integration of battle-tested workflows from Y.K. Dojo + ## [2.1.0] - 2026-01-10 ### Added diff --git a/README.md b/README.md index ad8816e..6f3cfe6 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ | File | Description | Reading Time | |------|-------------|--------------| -| [`english-ultimate-claude-code-guide.md`](./english-ultimate-claude-code-guide.md) | Complete guide (7500+ lines, 27K+ words) | ~3 hours | +| [`english-ultimate-claude-code-guide.md`](./english-ultimate-claude-code-guide.md) | Complete guide (8900+ lines, 33K+ words) | ~3 hours | | [`cheatsheet-en.md`](./cheatsheet-en.md) | 1-page printable daily reference | 5 minutes | | [`claude-setup-audit-prompt.md`](./claude-setup-audit-prompt.md) | Self-audit prompt for your setup | ~10 minutes | | [`examples/`](./examples/) | Production-ready commands, hooks, agents | Browse as needed | @@ -42,7 +42,7 @@ Transform this repository into an interactive AI-powered documentation explorer: - **Search semantically** beyond keyword matching - **Get summaries** of specific sections on demand -Perfect for quick lookups when you don't want to read the full 7500+ lines. +Perfect for quick lookups when you don't want to read the full 8900+ lines. --- @@ -284,6 +284,8 @@ Want to know if your Claude Code setup follows best practices? - [zebbern/claude-code-guide](https://github.com/zebbern/claude-code-guide) — Comprehensive reference & troubleshooting guide with cybersecurity focus (excellent for security practitioners) - [Claudelog.com](https://claudelog.com/) — Tips, patterns & tutorials (highly recommended for all users) - [ykdojo/claude-code-tips](https://github.com/ykdojo/claude-code-tips) — Practical tips & productivity techniques (voice workflows, context management, terminal efficiency) + - Additional topics worth exploring: voice transcription (superwhisper/MacWhisper), tmux autonomous testing, cc-safe tool, cascade method, container experimentation, half-clone technique +- [DeepTo Claude Code Guide](https://cc.deeptoai.com/docs/en/best-practices/claude-code-comprehensive-guide) — Comprehensive best practices covering XML-structured prompts, session continuation, image processing, Unix piping workflows, and cost tracking (ccusage tool) ### Community Curated Lists - [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) — Commands, workflows, IDE integrations @@ -316,4 +318,4 @@ You are free to share and adapt this material, provided you give appropriate cre --- -*Last updated: January 2026 | Version 2.1* \ No newline at end of file +*Last updated: January 2026 | Version 2.3* \ No newline at end of file diff --git a/english-ultimate-claude-code-guide.md b/english-ultimate-claude-code-guide.md index f7dd63e..539da6f 100644 --- a/english-ultimate-claude-code-guide.md +++ b/english-ultimate-claude-code-guide.md @@ -10,7 +10,7 @@ **Last updated**: January 2026 -**Version**: 2.1 +**Version**: 2.2 --- @@ -374,6 +374,191 @@ You: Fix the authentication bug in @src/auth/middleware.ts Claude: [Immediately loads file and proposes fix] ``` +#### Working with Images and Screenshots + +Claude Code supports **direct image input** for visual analysis, mockup implementation, and design feedback. + +**How to use images**: + +1. **Paste directly in terminal** (macOS/Linux/Windows with modern terminal): + - Copy screenshot or image to clipboard (`Cmd+Shift+4` on macOS, `Win+Shift+S` on Windows) + - In Claude Code session, paste with `Cmd+V` / `Ctrl+V` + - Claude receives the image and can analyze it + +2. **Drag and drop** (some terminals): + - Drag image file into terminal window + - Claude loads and processes the image + +3. **Reference with path**: + ```bash + Analyze this mockup: /path/to/design.png + ``` + +**Common use cases**: + +```bash +# Implement UI from mockup +You: [Paste screenshot of Figma design] +Implement this login screen in React with Tailwind CSS + +# Debug visual issues +You: [Paste screenshot of broken layout] +The button is misaligned. Fix the CSS. + +# Analyze diagrams +You: [Paste architecture diagram] +Explain this system architecture and identify potential bottlenecks + +# Code from whiteboard +You: [Paste photo of whiteboard algorithm] +Convert this algorithm to Python code + +# Accessibility audit +You: [Paste screenshot of UI] +Review this interface for WCAG 2.1 compliance issues +``` + +**Supported formats**: PNG, JPG, JPEG, WebP, GIF (static) + +**Best practices**: +- **High contrast**: Ensure text/diagrams are clearly visible +- **Crop relevantly**: Remove unnecessary UI elements for focused analysis +- **Annotate when needed**: Circle/highlight specific areas you want Claude to focus on +- **Combine with text**: "Focus on the header section" provides additional context + +**Example workflow**: +``` +You: [Paste screenshot of error message in browser console] +This error appears when users click the submit button. Debug it. + +Claude: I can see the error "TypeError: Cannot read property 'value' of null". +This suggests the form field reference is incorrect. Let me check your form handling code... +[Reads relevant files and proposes fix] +``` + +**Limitations**: +- Images consume significant context tokens (equivalent to ~1000-2000 words of text) +- Use `/status` to monitor context usage after pasting images +- Consider describing complex diagrams textually if context is tight +- Some terminals may not support clipboard image pasting (fallback: save and reference file path) + +> **💡 Pro tip**: Take screenshots of error messages, design mockups, and documentation instead of describing them textually. Visual input is often faster and more precise than written descriptions. + +#### Session Continuation and Resume + +Claude Code allows you to **continue previous conversations** across terminal sessions, maintaining full context and conversation history. + +**Two ways to resume**: + +1. **Continue last session** (`--continue` or `-c`): + ```bash + # Automatically resumes your most recent conversation + claude --continue + # Short form + claude -c + ``` + +2. **Resume specific session** (`--resume ` or `-r `): + ```bash + # Resume a specific session by ID + claude --resume abc123def + # Short form + claude -r abc123def + ``` + +**Finding session IDs**: + +```bash +# List recent sessions with IDs +claude mcp call serena list_sessions + +# Sessions are also shown when you exit +You: /exit +Session ID: abc123def (saved for resume) +``` + +**Common use cases**: + +| Scenario | Command | Why | +|----------|---------|-----| +| Interrupted work | `claude -c` | Pick up exactly where you left off | +| Multi-day feature | `claude -r abc123` | Continue complex task across days | +| After break/meeting | `claude -c` | Resume without losing context | +| Parallel projects | `claude -r ` | Switch between different project contexts | +| Code review follow-up | `claude -r ` | Address review comments in original context | + +**Example workflow**: + +```bash +# Day 1: Start implementing authentication +cd ~/project +claude +You: Implement JWT authentication with refresh tokens +Claude: [Analysis and initial implementation] +You: /exit +Session ID: auth-feature-xyz (27% context used) + +# Day 2: Continue the work +cd ~/project +claude --continue +Claude: Resuming session auth-feature-xyz... +You: Add rate limiting to the auth endpoints +Claude: [Continues with full context of Day 1 work] +``` + +**Best practices**: + +- **Use `/exit` properly**: Always exit with `/exit` or `Ctrl+D` (not force-kill) to ensure session is saved +- **Descriptive final messages**: End sessions with context ("Ready for testing") so you remember the state when resuming +- **Check context before resuming**: High-context sessions (>75%) may need `/compact` after resuming +- **Session naming**: Use meaningful session IDs when available to identify different work streams + +**Resume vs. fresh start**: + +| Use Resume When... | Start Fresh When... | +|-------------------|---------------------| +| Continuing a specific feature/task | Switching to unrelated work | +| Building on previous decisions | Previous session went off track | +| Context is still relevant (<75%) | Context is bloated (>90%) | +| Multi-step implementation in progress | Quick one-off questions | + +**Limitations**: + +- Sessions are stored locally (not synced across machines) +- Very old sessions may be pruned (depends on local storage limits) +- Corrupted sessions can't be resumed (start fresh with `/clear`) +- Cannot resume sessions started with different model or MCP config + +**Context preservation**: + +When you resume, Claude retains: +- ✅ Full conversation history +- ✅ Files previously read/edited +- ✅ CLAUDE.md and project settings +- ✅ MCP server state (if Serena is used) +- ✅ Uncommitted code changes awareness + +**Combining with MCP Serena**: + +For advanced session management with project memory and symbol tracking: + +```bash +# Initialize Serena memory for the project +claude mcp call serena initialize_session + +# Work with full session persistence +You: Implement user authentication +Claude: [Works with Serena tracking symbols and context] + +# Exit and resume later with full project memory +claude -c +Claude: [Resumes with Serena's persistent project understanding] +``` + +> **💡 Pro tip**: Use `claude -c` as your default way to start Claude Code in active projects. This ensures you never lose context from previous sessions unless you explicitly want a fresh start with `claude` (no flags). + +> **Source**: [DeepTo Claude Code Guide - Context Resume Functions](https://cc.deeptoai.com/docs/en/best-practices/claude-code-comprehensive-guide) + ## 1.4 Permission Modes Claude Code has three permission modes that control how much autonomy Claude has: @@ -968,6 +1153,40 @@ Claude Code │ Ctx(u): 45% │ Cost: $0.23 │ Session: 1h 23m ↑ Current session cost ``` +**Advanced tracking with `ccusage`**: + +The `ccusage` CLI tool provides detailed cost analytics beyond the `/cost` command: + +```bash +ccusage # Overview all periods +ccusage --today # Today's costs +ccusage --month # Current month +ccusage --session # Active session breakdown +ccusage --model-breakdown # Cost by model (Sonnet/Opus/Haiku) +``` + +**Example output**: +``` +┌──────────────────────────────────────────────────────┐ +│ USAGE SUMMARY - January 2026 │ +├──────────────────────────────────────────────────────┤ +│ Today $2.34 (12 sessions) │ +│ This week $8.91 (47 sessions) │ +│ This month $23.45 (156 sessions) │ +├──────────────────────────────────────────────────────┤ +│ MODEL BREAKDOWN │ +│ Sonnet 3.5 85% $19.93 │ +│ Opus 4 12% $2.81 │ +│ Haiku 3.5 3% $0.71 │ +└──────────────────────────────────────────────────────┘ +``` + +**Why use `ccusage` over `/cost`?** +- **Historical trends**: Track usage patterns over days/weeks/months +- **Model breakdown**: See which model tier drives costs +- **Budget planning**: Set monthly spending targets +- **Team analytics**: Aggregate costs across developers + **Monthly tracking**: Check your Anthropic Console for detailed usage: @@ -1475,6 +1694,459 @@ Login is broken The more context you provide, the better Claude can help. +## 2.6 Structured Prompting with XML Tags + +XML-structured prompts provide **semantic organization** for complex requests, helping Claude distinguish between different aspects of your task for clearer understanding and better results. + +### What Are XML-Structured Prompts? + +XML tags act as **labeled containers** that explicitly separate instruction types, context, examples, constraints, and expected output format. + +**Basic syntax**: + +```xml + + Your main task description here + + + + Background information, project details, or relevant state + + + + Reference code or examples to follow + + + + - Limitation 1 + - Limitation 2 + - Requirement 3 + + + + Expected format or structure of the response + +``` + +### Why Use XML Tags? + +| Benefit | Description | +|---------|-------------| +| **Separation of concerns** | Different aspects of the task are clearly delineated | +| **Reduced ambiguity** | Claude knows which information serves what purpose | +| **Better context handling** | Helps Claude prioritize main instructions over background info | +| **Consistent formatting** | Easier to template complex requests | +| **Multi-faceted requests** | Complex tasks with multiple requirements stay organized | + +### Common Tags and Their Uses + +**Core Instruction Tags**: + +```xml +Main task +Specific subtask +What should I do about X? +Achieve state Y +``` + +**Context and Information Tags**: + +```xml +Project uses Next.js 14 +Users report slow page loads +Migration from Pages Router +Currently on feature-branch +``` + +**Code and Example Tags**: + +```xml + + // Existing pattern to follow + const user = await getUser(id); + + + + // Code that needs modification + + + + // What the result should look like + +``` + +**Constraint and Rule Tags**: + +```xml + + - Must maintain backward compatibility + - No breaking changes to public API + - Maximum 100ms response time + + + + - TypeScript strict mode + - 100% test coverage + - Accessible (WCAG 2.1 AA) + + + + - Don't use any for types + - Don't modify the database schema + +``` + +### Practical Examples + +**Example 1: Code Review with Context** + +```xml + +Review this authentication middleware for security vulnerabilities + + + +This middleware is used in a financial application handling sensitive user data. +We follow OWASP Top 10 guidelines and need PCI DSS compliance. + + + +async function authenticate(req, res, next) { + const token = req.headers.authorization?.split(' ')[1]; + if (!token) return res.status(401).json({ error: 'No token' }); + + const decoded = jwt.verify(token, process.env.JWT_SECRET); + req.user = decoded; + next(); +} + + + +- Point out any security risks +- Suggest PCI DSS compliant alternatives +- Consider timing attacks and token leakage + + + +Provide: +1. List of security issues found +2. Severity rating for each (Critical/High/Medium/Low) +3. Specific code fixes with examples +4. Additional security hardening recommendations + +``` + +**Example 2: Feature Implementation with Examples** + +```xml + +Add a rate limiting system to our API endpoints + + + +Current stack: Express.js + Redis +No rate limiting currently exists +Experiencing API abuse from specific IPs + + + +- 100 requests per minute per IP for authenticated users +- 20 requests per minute per IP for unauthenticated +- Custom limits for premium users (stored in database) +- Return 429 status with Retry-After header + + + +// Existing middleware pattern we use +app.use(authenticate); +app.use(authorize(['admin', 'user'])); + + + +- Must not impact existing API performance +- Redis connection should be reused +- Handle Redis connection failures gracefully + + + +Provide: +1. Rate limiter middleware implementation +2. Redis configuration +3. Unit tests +4. Documentation for the team + +``` + +**Example 3: Bug Investigation with State** + +```xml + +Investigate why user sessions are expiring prematurely + + + +Users report being logged out after 5-10 minutes of activity, +but session timeout is configured for 24 hours. + + + +- Next.js 14 App Router with next-auth +- PostgreSQL session store +- Load balanced across 3 servers +- Issue started after deploying v2.3.0 last week + + + +Git diff between v2.2.0 (working) and v2.3.0 (broken) shows changes to: +- middleware.ts (session refresh logic) +- auth.config.ts (session strategy) +- database.ts (connection pooling) + + + +- Don't suggest reverting the deploy +- Production issue, needs quick resolution +- Must maintain session security + + + +Provide: +1. Root cause hypothesis +2. Files to investigate (in priority order) +3. Debugging commands to run +4. Potential fixes with trade-offs + +``` + +### Advanced Patterns + +**Nested Tags for Complex Hierarchy**: + +```xml + +Refactor authentication system + + Update user model + + - Preserve existing user IDs + - Add migration for email verification + + + + + Implement OAuth providers + + - Google and GitHub OAuth + - Reuse existing session logic + + + +``` + +**Multiple Examples with Labels**: + +```xml + + // Old approach with callback hell + getUser(id, (user) => { + getOrders(user.id, (orders) => { + res.json({ user, orders }); + }); + }); + + + + // New async/await pattern + const user = await getUser(id); + const orders = await getOrders(user.id); + res.json({ user, orders }); + +``` + +**Conditional Instructions**: + +```xml + +Optimize database query performance + + + +Query currently takes 2.5 seconds for 10,000 records + + + + + - Use EXPLAIN ANALYZE + - Consider materialized views + + + + - Use EXPLAIN with query plan analysis + - Consider query cache + + +``` + +### When to Use XML-Structured Prompts + +| Scenario | Recommended? | Why | +|----------|--------------|-----| +| Simple one-liner requests | ❌ No | Overhead outweighs benefit | +| Multi-step feature implementation | ✅ Yes | Separates goals, constraints, examples | +| Bug investigation with context | ✅ Yes | Distinguishes symptoms from environment | +| Code review with specific criteria | ✅ Yes | Clear separation of code, context, requirements | +| Architecture planning | ✅ Yes | Organizes goals, constraints, trade-offs | +| Quick typo fix | ❌ No | Unnecessary complexity | + +### Best Practices + +**Do's**: +- ✅ Use descriptive tag names that clarify purpose +- ✅ Keep tags consistent across similar requests +- ✅ Combine with CLAUDE.md for project-specific tag conventions +- ✅ Nest tags logically when representing hierarchy +- ✅ Use tags to separate "what" from "why" from "how" + +**Don'ts**: +- ❌ Over-structure simple requests (adds noise) +- ❌ Mix tag purposes (e.g., constraints inside code examples) +- ❌ Use generic tags (``, ``) without clear meaning +- ❌ Nest too deeply (>3 levels becomes hard to read) + +### Integration with CLAUDE.md + +You can standardize XML tag usage in your project's CLAUDE.md: + +```markdown +# XML Prompt Conventions + +When making complex requests, use this structure: + +Main task + + + Project context and state + + + + Reference implementations + + + + Technical and business requirements + + + + Expected deliverables + + +## Project-Specific Tags + +- `` - API endpoint design specifications +- `` - WCAG requirements and ARIA considerations +- `` - Performance budgets and optimization goals +``` + +### Combining with Other Features + +**XML + Plan Mode**: + +```xml +Plan the migration from REST to GraphQL + + +Currently 47 REST endpoints serving mobile and web clients + + + +- Must maintain REST endpoints during transition (6-month overlap) +- Mobile app can't be force-updated immediately + + + +Multi-phase migration plan with rollback strategy + +``` + +Then use `/plan` to explore read-only before implementation. + +**XML + Cost Awareness**: + +For large requests, structure with XML to help Claude understand scope and estimate token usage: + +```xml +Analyze all TypeScript files for unused imports + + + src/ directory (~200 files) + + + + Summary report only (don't list every file) + +``` + +This helps Claude optimize the analysis approach and reduce token consumption. + +### Example Template Library + +Create reusable templates in `claudedocs/templates/`: + +**`claudedocs/templates/code-review.xml`**: + +```xml + +Review the following code for quality and best practices + + + +[Describe the component's purpose and architecture context] + + + +[Paste code here] + + + +- Security vulnerabilities +- Performance bottlenecks +- Maintainability issues +- Test coverage gaps + + + +1. Issues found (categorized by severity) +2. Specific recommendations with code examples +3. Priority order for fixes + +``` + +**Usage**: + +```bash +cat claudedocs/templates/code-review.xml | \ + sed 's/\[Paste code here\]/'"$(cat src/auth.ts)"'/' | \ + claude -p "Process this review request" +``` + +### Limitations and Considerations + +**Token overhead**: XML tags consume tokens. For simple requests, natural language is more efficient. + +**Not required**: Claude understands natural language perfectly well. Use XML when structure genuinely helps. + +**Consistency matters**: If you use XML tags, be consistent. Mixing styles within a session can confuse context. + +**Learning curve**: Team members need to understand the tag system. Document your conventions in CLAUDE.md. + +> **💡 Pro tip**: Start with natural language prompts. Introduce XML structure when: +> - Requests have 3+ distinct aspects (instruction + context + constraints) +> - Ambiguity causes Claude to misunderstand your intent +> - Creating reusable prompt templates +> - Working with junior developers who need structured communication patterns + +> **Source**: [DeepTo Claude Code Guide - XML-Structured Prompts](https://cc.deeptoai.com/docs/en/best-practices/claude-code-comprehensive-guide) + --- # 3. Memory & Settings @@ -4383,6 +5055,186 @@ claude --headless --timeout 300 "Build the project" claude --headless --model sonnet "Analyze code quality" ``` +### Unix Piping Workflows + +Claude Code supports **Unix pipe operations**, enabling powerful shell integration for automated code analysis and transformation. + +**How piping works**: + +```bash +# Pipe content to Claude with a prompt +cat file.txt | claude -p 'analyze this code' + +# Pipe command output for analysis +git diff | claude -p 'explain these changes' + +# Chain commands with Claude +npm test 2>&1 | claude -p 'summarize test failures and suggest fixes' +``` + +**Common patterns**: + +1. **Code review automation**: + ```bash + git diff main...feature-branch | claude -p 'Review this diff for security issues' + ``` + +2. **Log analysis**: + ```bash + tail -n 100 /var/log/app.log | claude -p 'Find the root cause of errors' + ``` + +3. **Test output parsing**: + ```bash + npm test 2>&1 | claude -p 'Create a summary of failing tests with priority order' + ``` + +4. **Documentation generation**: + ```bash + cat src/api/*.ts | claude -p 'Generate API documentation in Markdown' + ``` + +5. **Batch file analysis**: + ```bash + find . -name "*.js" -exec cat {} \; | claude -p 'Identify unused dependencies' + ``` + +**Using with `--output-format`**: + +```bash +# Get structured JSON output +git status --short | claude -p 'Categorize changes' --output-format json + +# Stream JSON for real-time processing +cat large-file.txt | claude -p 'Analyze line by line' --output-format stream-json +``` + +**Best practices**: + +- **Be specific**: Clear prompts yield better results + ```bash + # Good: Specific task + git diff | claude -p 'List all function signature changes' + + # Less effective: Vague request + git diff | claude -p 'analyze this' + ``` + +- **Limit input size**: Pipe only relevant content to avoid context overload + ```bash + # Good: Filtered scope + git diff --name-only | head -n 10 | xargs cat | claude -p 'review' + + # Risky: Could exceed context + cat entire-codebase/* | claude -p 'review' + ``` + +- **Use non-interactive mode**: Add `--headless` for automation + ```bash + cat file.txt | claude --headless -p 'fix linting errors' > output.txt + ``` + +- **Combine with jq for JSON**: Parse Claude's JSON output + ```bash + echo "const x = 1" | claude -p 'analyze' --output-format json | jq '.suggestions[]' + ``` + +**Output format control**: + +The `--output-format` flag controls Claude's response format: + +| Format | Use Case | Example | +|--------|----------|---------| +| `text` | Human-readable output (default) | `claude -p 'explain' --output-format text` | +| `json` | Machine-parseable structured data | `claude -p 'analyze' --output-format json` | +| `stream-json` | Real-time streaming for large outputs | `claude -p 'transform' --output-format stream-json` | + +**Example JSON workflow**: + +```bash +# Get structured analysis +git log --oneline -10 | claude -p 'Categorize commits by type' --output-format json + +# Output: +# { +# "categories": { +# "features": ["add user auth", "new dashboard"], +# "fixes": ["fix login bug", "resolve crash"], +# "chores": ["update deps", "refactor tests"] +# }, +# "summary": "10 commits: 2 features, 2 fixes, 6 chores" +# } +``` + +**Integration with build scripts** (`package.json`): + +```json +{ + "scripts": { + "claude-review": "git diff main | claude -p 'Review for security issues' --output-format json > review.json", + "claude-test-summary": "npm test 2>&1 | claude --headless -p 'Summarize failures and suggest fixes'", + "claude-docs": "cat src/**/*.ts | claude -p 'Generate API documentation' > API.md", + "precommit-check": "git diff --cached | claude --headless -p 'Check for secrets or anti-patterns' && git diff --cached | prettier --check" + } +} +``` + +**CI/CD integration example**: + +```yaml +# .github/workflows/claude-review.yml +name: AI Code Review +on: [pull_request] + +jobs: + claude-review: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Install Claude Code + run: npm install -g @anthropic-ai/claude-code + + - name: Run Claude Review + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + run: | + git diff origin/main...HEAD | \ + claude --headless -p 'Review this PR diff for security issues, performance problems, and code quality. Format as JSON.' \ + --output-format json > review.json + + - name: Comment on PR + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const review = JSON.parse(fs.readFileSync('review.json', 'utf8')); + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: `## 🤖 Claude Code Review\n\n${review.summary}` + }); +``` + +**Limitations**: + +- **Context size**: Large pipes may exceed token limits (monitor with `/status`) +- **Interactive prompts**: Use `--headless` for automation to avoid blocking +- **Error handling**: Pipe failures don't always propagate; add `set -e` for strict mode +- **API costs**: Automated pipes consume API credits; monitor usage with `ccusage` + +> **💡 Pro tip**: Combine piping with aliases for frequently used patterns: +> ```bash +> # Add to ~/.bashrc or ~/.zshrc +> alias claude-review='git diff | claude -p "Review for bugs and suggest improvements"' +> alias claude-logs='tail -f /var/log/app.log | claude -p "Monitor for errors and alert on critical issues"' +> ``` + +> **Source**: [DeepTo Claude Code Guide - Unix Piping](https://cc.deeptoai.com/docs/en/best-practices/claude-code-comprehensive-guide) + ### Git Hooks Integration > **Windows Note**: Git hooks run in Git Bash on Windows, so the bash syntax below works. Alternatively, you can create `.cmd` or `.ps1` versions and reference them from a wrapper script. @@ -8409,6 +9261,14 @@ SuperClaude transforms Claude Code into a structured development platform throug > **Tip**: These resources evolve quickly. Star repos you find useful to track updates. +**Additional topics from ykdojo worth exploring** (not yet integrated in this guide): +- **Voice transcription workflows** - Using superwhisper/MacWhisper for faster input than typing +- **Tmux for autonomous testing** - Running interactive tools in tmux sessions for automated testing +- **cc-safe security tool** - Auditing approved commands to prevent accidental deletions +- **Cascade method** - Multitasking pattern with 3-4 terminal tabs for parallel work streams +- **Container experimentation** - Using Docker with `--dangerously-skip-permissions` for safe experimental work +- **Half-clone technique** - Manual context trimming to keep recent conversation history only + ### Tools #### Audit Your Setup @@ -8634,4 +9494,4 @@ Thumbs.db **Contributions**: Issues and PRs welcome. -**Last updated**: January 2026 | **Version**: 2.1 +**Last updated**: January 2026 | **Version**: 2.3 diff --git a/examples/memory/CLAUDE.md.personal-template b/examples/memory/CLAUDE.md.personal-template index 977b2d4..19900cb 100644 --- a/examples/memory/CLAUDE.md.personal-template +++ b/examples/memory/CLAUDE.md.personal-template @@ -1,5 +1,4 @@ # Personal Claude Memory - > This file provides Claude with your personal preferences. > Place at: ~/.claude/CLAUDE.md (global, applies to all projects).