+sequenceDiagram + participant Customer + participant App + participant Kitchen + participant Driver + Customer->>App: Place order (pepperoni, large) + App->>Kitchen: Send order ticket + Kitchen-->>App: Order ready (15 min) + App->>Driver: Assign delivery + Driver-->>Customer: Pizza delivered 🍕 ++ + +EOF +open /tmp/pizza-flow.html +``` + +See that flow? Customer -> App -> Kitchen -> Driver -> Customer. + +Now here's the raw text that generated it: + +``` +sequenceDiagram + participant Customer + participant App + participant Kitchen + participant Driver + Customer->>App: Place order (pepperoni, large) + App->>Kitchen: Send order ticket + Kitchen-->>App: Order ready (15 min) + App->>Driver: Assign delivery + Driver-->>Customer: Pizza delivered 🍕 +``` + +That text is hard for you to parse. But Claude reads it instantly. + +For a real app, you'd have diagrams for auth flows, database operations, API routes - everything that explains how your code connects. + +STOP: Makes sense? The diagram is for Claude, not for you. + +USER: Yes / Got it / Interesting + +## The Command + +So how do we get these diagrams INTO Claude's brain before we start working? + +Normally you start Claude Code by typing `claude` in your terminal. But you can add flags to customize how it starts up. + +Here's the magic command: + +``` +claude --append-system-prompt "$(cat .ai/diagrams/*.md)" +``` + +You type this in your terminal INSTEAD of just `claude`. Let me break it down: + +- `claude` - starts Claude Code (you know this part) +- `--append-system-prompt` - a flag that says "add this text to Claude's base instructions" +- `"$(cat .ai/diagrams/*.md)"` - reads all the .md files from the diagrams folder and passes them in + +The result: Claude starts up with your architecture diagrams already loaded. When you ask "explain the pizza ordering flow" - it already knows. No searching. + +Here's what's in the example diagram file at `.ai/diagrams/example-pizza-flow.md`: + +ACTION: Print the contents of `.ai/diagrams/example-pizza-flow.md` + +## Try It Yourself + +Let's try it. I've included a sample diagram in this project at `.ai/diagrams/example-pizza-flow.md`. + +Here's what to do: + +1. Open a NEW terminal window (keep this lesson running here) +2. Navigate to this project folder. IMPORTANT - use quotes because the path has spaces: + ``` + cd "YOUR_PATH_TO/advanced-claude-workflows" + ``` + ACTION: Tell the user the exact quoted path to this folder so they can copy it. + +3. Run: `claude --append-system-prompt "$(cat .ai/diagrams/*.md)"` +4. When that Claude starts, ask it: "Explain the pizza ordering flow" + +Watch what happens - no file reads, no searching. It just knows. + +STOP: Go try it now. Come back when you've seen how it responds. + +USER: [User returns after trying] + +That's the power of preloading context. No file searches. No exploration. Just answers. + +For larger projects, you'd have multiple diagram files - one for auth, one for database operations, one for API routes. Load what you need. + +STOP: Ready to learn how to make this easier with aliases? + +USER: Yes / Ready + +## Aliases + +That command is powerful but annoying to type every time. + +The solution: shell aliases. + +An alias is a shortcut you define in your terminal config. You type a short word, and your terminal expands it into a longer command. + +For example, if you add this line to your shell config file (~/.zshrc on Mac): + +``` +alias cdi="claude --append-system-prompt \"\$(cat .ai/diagrams/*.md)\"" +``` + +Then instead of typing that whole command, you just type: + +``` +cdi +``` + +And it starts Claude with your diagrams pre-loaded. + +Here are useful Claude Code aliases: + +```bash +alias x="claude --dangerously-skip-permissions" +# Type `x` to start Claude in "live dangerously" mode - no permission prompts + +alias h="claude --model claude-haiku-4-5-20251001" +# Type `h` to start Claude with the fast (but less smart) Haiku model + +alias cdi="claude --append-system-prompt \"\$(cat .ai/diagrams/*.md)\"" +# Type `cdi` to start Claude with your diagrams pre-loaded +``` + +You add these lines to your ~/.zshrc (Mac) or ~/.bashrc (Linux) file. Then run `source ~/.zshrc` to activate them. + +STOP: Which of these would be most useful for your workflow? + +USER: x (bypass) / h (fast model) / cdi (diagrams) / All of them + +## Create Your Alias + +Let's create a custom alias for YOUR workflow. + +Think about: +- What flags do you use most often? +- What context do you always want loaded? +- Do you have project-specific needs? + +Give me a short name (1-3 letters) and what you want it to do. + +STOP: What alias do you want to create? + +USER: [User describes their alias] + +ACTION: +1. Generate the alias command +2. Write it to `my-aliases.md` with full instructions +3. OFFER to help add it to their ~/.zshrc directly. Say: "Want me to add this to your ~/.zshrc so it works immediately? I'll append just the alias line - won't touch anything else." + +If they say yes: +- Read their ~/.zshrc first +- Append ONLY the alias line at the end (don't modify existing content) +- Use proper quoting for any paths with spaces +- Run `source ~/.zshrc` equivalent or tell them to restart terminal + +STOP: Did that work? Try typing your new alias in a fresh terminal. + +USER: [Confirms it works] + +## Stop Hooks + +Now for the most powerful technique: stop hooks. + +Here's a frustrating pattern you've probably experienced: + +1. You ask Claude to write some code +2. Claude writes it and says "Done!" +3. You run the code - there are TypeScript errors +4. You paste the errors back to Claude +5. Claude fixes them, says "Done!" again +6. You run again - more errors +7. Repeat until you want to throw your laptop + +The problem: Claude doesn't know about errors unless you tell it. + +The solution: Make Claude automatically check its own work before saying "Done." + +STOP: Have you experienced this loop - Claude saying it's done when it's not? + +USER: Yes / All the time / Sometimes + +## Watch It Work + +Let me show you instead of explaining. This project has a stop hook already configured. + +Here's what's about to happen: +1. You'll ask me to create a JavaScript file +2. I'll create it and try to stop +3. The hook will block me because there's no "// COMPLETE" comment +4. I'll see the error, add the comment, and try again +5. The hook will pass + +Ready? Ask me: "Create a hook_demo.js file that logs 'Hello World'" + +STOP: Ask me to create the file. + +USER: Create a hook_demo.js file that logs 'Hello World' + +ACTION: +1. Create hook_demo.js with ONLY console.log('Hello World'); - DO NOT add any comment +2. Stop responding and wait for the hook to run +3. The hook WILL block you with an error message - this is expected +4. When you see the block message, THEN add the // COMPLETE comment +5. After the hook passes, continue to explain what happened + +IMPORTANT: Do NOT read the settings file or anticipate the hook. Just create the file and stop. Let the hook catch you. + +Did you see that? I got blocked, read the reason, and fixed it myself. + +That's a stop hook in action. Every time I try to finish responding, Claude Code runs a check. If the check fails, I see the error and fix it automatically. + +No copy-pasting errors. No back-and-forth. I just keep working until the check passes. + +STOP: Makes sense so far? + +USER: Yes / Got it + +## How Stop Hooks Work + +A "hook" is code that runs automatically at a certain moment. + +A "stop hook" runs every time Claude finishes a response - right before it waits for your next input. + +You configure it to run any command. If the command finds problems, Claude sees them and fixes them automatically. This loops until all checks pass. + +``` +Claude finishes -> Stop hook runs -> Checks code... + |-- Errors found -> Errors sent back, Claude fixes, tries again + |-- No errors -> Claude actually stops +``` + +STOP: Clear on the concept? + +USER: Yes / Makes sense + +## Hook Configuration + +Claude Code looks for configuration in a `.claude` folder in your project. + +Inside that folder, `settings.local.json` holds your personal settings for this project. + +Here's the hook that just blocked me: + +```json +{ + "hooks": { + "Stop": [ + { + "hooks": [ + { + "type": "command", + "command": "[ ! -f hook_demo.js ] || grep -q '// COMPLETE' hook_demo.js || echo '{\"decision\":\"block\",\"reason\":\"You forgot to add the // COMPLETE comment to hook_demo.js\"}'" + } + ] + } + ] + } +} +``` + +STOP: Want me to break down how that command works? + +USER: Yes / Skip it + +If user says yes: + +Let me break down that command: + +- `[ ! -f hook_demo.js ]` - if hook_demo.js doesn't exist, do nothing (pass) +- `||` - OR... +- `grep -q '// COMPLETE' hook_demo.js` - if hook_demo.js HAS the comment, do nothing (pass) +- `||` - OR... +- `echo '{...}'` - output JSON telling Claude what went wrong (block) + +In plain English: "Only complain if hook_demo.js exists but lacks the // COMPLETE comment." + +This hook uses only basic shell commands - no installs needed. Works on any Mac or Linux. + +## The Pattern + +The pattern for any hook is simple: + +1. Run a check command (grep, npm test, typecheck, whatever) +2. If check fails -> output JSON with "decision": "block" and a "reason" +3. If check passes -> output nothing + +The JSON becomes Claude's next instruction: + +```json +{ + "decision": "block", + "reason": "You forgot to add the // COMPLETE comment." +} +``` + +Claude sees this, understands the problem, and fixes it automatically. + +STOP: Got the pattern? + +USER: Yes / Got it + +## Why This Matters + +Think about what this enables: + +**Without hooks:** You're the quality gate. You run tests, see errors, paste them back, wait for fixes, run again. Tedious. + +**With hooks:** Claude becomes self-correcting. It can't say "done" until the checks actually pass. You can walk away and come back to working code. + +This is huge for: +- Long-running tasks (Claude keeps going until tests pass) +- Maintaining code quality (every change gets checked) +- Building trust (you know Claude won't leave broken code) + +STOP: See how this changes the workflow? + +USER: Yes / Definitely + +## Other Hooks You Could Set Up + +The demo used a simple grep check. Here's what you'd use in real projects: + +```bash +# TypeScript type checking +npm run typecheck 2>&1 || echo '{"decision":"block","reason":"TypeScript errors found"}' + +# Linting +npm run lint 2>&1 || echo '{"decision":"block","reason":"Linting errors found"}' + +# Tests +npm test 2>&1 || echo '{"decision":"block","reason":"Tests failing"}' + +# Build check +npm run build 2>&1 || echo '{"decision":"block","reason":"Build failed"}' +``` + +You can chain multiple checks. If ANY fail, Claude keeps working. + +STOP: What quality checks would you add to YOUR projects? + +USER: [User responds with their ideas] + +Good thinking. The pattern is always the same: +1. Run your check command +2. If it fails, output JSON with the reason +3. If it passes, output nothing + +STOP: Ready for the final two topics? They're more about mindset than configuration. + +USER: Yes / Ready + +## The Infinite Junior Engineer + +Here's a powerful way to think about AI automation: + +Imagine you had infinite junior engineers - always available, no meetings, happy to do tedious work. What would you have them do? + +Most people think: "Write code faster." + +But the real answer is all the stuff AROUND the code: +- Trace who wrote this code and why +- Find the history of every file involved +- Write a risk assessment before touching anything +- Generate a tech spec for review +- Document everything after +- Summarize the PR for reviewers +- Write the commit messages + +All of that is a prompt. All of it can be automated. + +The AI isn't replacing your judgment. It's doing the boring prep work so you can focus on decisions that actually matter. + +STOP: What "drudgery" tasks would you hand off to infinite junior engineers? + +USER: [User responds] + +Good thinking. Those are exactly the kinds of tasks to automate. + +## Handling Drift + +One last technique: what to do when Claude goes off the rails. + +Sometimes Claude gets confused and starts doing the wrong thing. You try to correct it. It gets more confused. You're both frustrated. + +Here's a better approach: + +1. Don't fight it - trying to steer a confused AI back rarely works +2. Export the conversation (Claude Code has an export command) +3. Paste it into a DIFFERENT model (ChatGPT, Gemini, etc.) +4. Ask that model: "Where did this conversation go wrong? How should I have prompted differently?" +5. Start fresh with a better prompt + +Why does this work? The second model isn't "stuck" in the same confusion. It can look at the conversation objectively and spot where things derailed. + +Think of it like asking a colleague to review a confusing email thread. Fresh eyes see what you can't. + +STOP: Have you ever tried using one AI to debug another? + +USER: Yes / No / Interesting idea + +## Wrap Up + +Here's what you learned: + +1. **Mermaid diagrams** - Preload architecture context with --append-system-prompt +2. **Aliases** - One-letter shortcuts for your common Claude configurations +3. **Stop hooks** - Automatic quality gates that make Claude self-correct +4. **Infinite junior engineer** - Think about automation as prep work, not code writing +5. **Drift recovery** - Use a second model as mediator when things go wrong + +You have: +- A sample diagram in `.ai/diagrams/` +- A working stop hook in `.claude/settings.local.json` +- Your custom aliases in `my-aliases.md` + +The philosophy: "It's easier to edit than author." Get something generated - even if wrong - then iterate. + +Now go build something. + +## Notes for Claude + +**Teaching style:** +- Conversational, direct, no fluff +- Quote examples inline (user can't see file reads) +- Actually run bash commands to open the mermaid diagram in browser +- Actually use the Ask User Question tool for STOP points when possible +- Write real content to my-aliases.md + +**If user doesn't have an alias idea:** +- Suggest: combining bypass + diagrams, or project-specific context loading + +**If user seems confused:** +- Slow down, check understanding +- Offer to re-explain any technique + +**Success criteria:** +- User understands mermaid diagrams for context preloading +- User saw the diagram rendered in browser +- User has at least one custom alias in my-aliases.md +- User witnessed the stop hook demo (got blocked, self-corrected) +- User knows the "infinite junior engineer" mindset diff --git a/advanced-claude-workflows/my-aliases.md b/advanced-claude-workflows/my-aliases.md new file mode 100644 index 0000000..dafe002 --- /dev/null +++ b/advanced-claude-workflows/my-aliases.md @@ -0,0 +1,62 @@ +# My Claude Code Aliases + +## Your Alias + +```bash +alias h="claude --model claude-haiku-4-5-20251001" +``` + +Type `h` to start Claude with the fast Haiku model - great for quick tasks where speed matters. + +## How to Install + +1. Open your shell config: + ```bash + open ~/.zshrc + ``` + +2. Add this line at the bottom: + ```bash + alias h="claude --model claude-haiku-4-5-20251001" + ``` + +3. Save the file and reload: + ```bash + source ~/.zshrc + ``` + +4. Test it - just type `h` in any directory to start Claude with Haiku. + +## When to Use Haiku + +- Quick questions and lookups +- Simple file edits +- Code formatting or renaming +- Tasks where speed matters more than depth +- Exploratory work before diving deep + +## Other Useful Aliases (Optional) + +```bash +# Skip permission prompts (use with caution) +alias x="claude --dangerously-skip-permissions" + +# Load architecture diagrams at startup +alias cdi="claude --append-system-prompt \"\$(cat .ai/diagrams/*.md)\"" + +# Combo: Haiku + skip permissions +alias xh="claude --model claude-haiku-4-5-20251001 --dangerously-skip-permissions" + +# Combo: Haiku + diagrams +alias hdi="claude --model claude-haiku-4-5-20251001 --append-system-prompt \"\$(cat .ai/diagrams/*.md)\"" +``` + +## When to Use Each + +| Alias | Use When | +|-------|----------| +| `h` | Quick questions, simple tasks | +| `x` | You trust Claude and want no prompts | +| `cdi` | Starting work on a documented project | +| `xh` | Fast + no prompts | +| `hdi` | Fast + full context | diff --git a/advanced-claude-workflows/thumbnail.html b/advanced-claude-workflows/thumbnail.html new file mode 100644 index 0000000..7f38254 --- /dev/null +++ b/advanced-claude-workflows/thumbnail.html @@ -0,0 +1,156 @@ + + + + + +
Based on Claire Vo's interview with John Lindquist
+