{ "cells": [ { "cell_type": "markdown", "metadata": { }, "source": [ "*Module 6 Self-Driven Lab*\r\n", "\r\n", "# Claude Code \u0026 Skills\r\n", "\r\n", "**Objective:** master built-in tool selection and the fallback modification pattern.\r\n", "\r\n", "## Challenge Outline\r\n", "\r\n", "Build a complete notebook that demonstrates the following outcomes:\r\n", "\r\n", "- **Structural mapping:** use `Glob` to find all configuration files matching `**/*.config.ts`.\r\n", "- **Entry point search:** use `Grep` to find every instance of `\"Invalid Token\"` and identify where authentication logic is defined.\r\n", "- **Tracing and reading:** use `Read` to inspect the source file found by `Grep`, identify the exported function, then use `Grep` again to find all callers.\r\n", "- **The fallback move:** attempt to use `Edit` to add a line where the target anchor text appears multiple times. Observe the failure, then use `Read` to get the full file content and `Write` to replace it reliably.\r\n", "- **Divergent approaches:** use `fork_session` to compare two different ways of fixing the authentication bug. Resume each branch to verify the fix.\r\n", "- **Skill review:** use the `skill-creator` skill to audit a custom skill for vague descriptions, missing trigger conditions, missing `Steps`, and whether supporting docs belong in `references/`.\r\n", "- **Personal skill variant:** create a user-scoped variant in `~/.claude/skills/` with a unique name, then document how it differs from the team skill without changing project files.\r\n", "- **Interview pattern:** prompt Claude to ask 2-3 clarifying questions before implementation, specifically probing cache invalidation, failure modes, and compatibility risks.\r\n", "- **CI review isolation:** run an independent `claude -p` review with `--output-format json` and `--json-schema`, then map findings to inline PR comments.\r\n", "\r\n", "Your solution should include enough code, output, or written observations to prove each outcome worked. Keep the notebook focused on final behavior and evidence rather than a guided walkthrough.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Student Workspace\n", "\n", "Use the sections below to build your solution. Each section maps to one required outcome from the challenge outline.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 1: Structural mapping\n", "\n", "use `Glob` to find all configuration files matching `**/*.config.ts`.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 1: Structural mapping\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 2: Entry point search\n", "\n", "use `Grep` to find every instance of `\"Invalid Token\"` and identify where authentication logic is defined.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 2: Entry point search\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 3: Tracing and reading\n", "\n", "use `Read` to inspect the source file found by `Grep`, identify the exported function, then use `Grep` again to find all callers.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 3: Tracing and reading\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 4: The fallback move\n", "\n", "attempt to use `Edit` to add a line where the target anchor text appears multiple times. Observe the failure, then use `Read` to get the full file content and `Write` to replace it reliably.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 4: The fallback move\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 5: Divergent approaches\n", "\n", "use `fork_session` to compare two different ways of fixing the authentication bug. Resume each branch to verify the fix.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 5: Divergent approaches\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 6: Skill review\n", "\n", "use the `skill-creator` skill to audit a custom skill for vague descriptions, missing trigger conditions, missing `Steps`, and whether supporting docs belong in `references/`.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 6: Skill review\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 7: Personal skill variant\n", "\n", "create a user-scoped variant in `~/.claude/skills/` with a unique name, then document how it differs from the team skill without changing project files.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 7: Personal skill variant\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 8: Interview pattern\n", "\n", "prompt Claude to ask 2-3 clarifying questions before implementation, specifically probing cache invalidation, failure modes, and compatibility risks.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 8: Interview pattern\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 9: CI review isolation\n", "\n", "run an independent `claude -p` review with `--output-format json` and `--json-schema`, then map findings to inline PR comments.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 9: CI review isolation\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Verification Notes\n", "\n", "Summarize the evidence that each part worked. Capture API signals, validation outcomes, errors, recovery behavior, cost observations, or comparisons required by this lab.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Verification notes\n", "# Record the evidence that proves each lab outcome worked.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "---\n", "\n", "## Answer Key\n", "\n", "The cells below contain the completed reference implementation/content for this module. Use this section only after attempting the self-driven lab." ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "*Module 6 of 12*\n", "\n", "# Claude Code \u0026 Skills\n", "\n", "This module shifts from basic configuration to advanced repository operations. It focuses on the practical judgment needed to explore large codebases without exhausting the context window, manage divergent exploration paths through forking, and make reliable file modifications when automated edits are ambiguous.\n", "\n", "\n", "## 1. Navigating Unfamiliar Codebases\n", "\n", "An architect must build understanding incrementally. Loading entire directories up front creates attention dilution: the model has too much low-signal text in context and starts missing the facts that matter.\n", "\n", "- **Glob pattern matching:** use `Glob` to find files by name or extension patterns, such as `**/*.test.tsx` or `**/*.config.ts`, rather than reading full directories.\n", "- **Content-based search:** use `Grep` to locate function entry points, exported names, error messages, and constants across the codebase.\n", "- **Flow tracing:** identify an exported name with `Read`, then use `Grep` to find all callers and trace usage through wrapper modules.\n", "- **Targeted reading:** use `Read` only after `Glob` or `Grep` has narrowed the candidate files.\n", "\n", "*incremental discovery pattern*\n", "```text\n", "Goal: understand an authentication failure without flooding context.\n", "\n", "1. Glob: \"**/*.config.ts\" to map configuration files.\n", "2. Grep: \"Invalid Token\" to locate the error source.\n", "3. Read: inspect the matching source file and identify the exported function.\n", "4. Grep: search for that exported function to find all callers.\n", "5. Read: inspect only the caller files needed to understand the flow.\n", "```\n", "\n", "## 2. Reliable Modifications\n", "\n", "Production modifications must be deterministic. Claude Code should prefer the smallest reliable edit, then escalate to a full-file replacement only when the targeted edit is ambiguous.\n", "\n", "- **The `Edit` tool:** preferred for targeted changes using unique text matching. It is more token-efficient and lower risk than full-file writes.\n", "- **The fallback pattern:** if `Edit` fails because the target text appears multiple times, use `Read` to load the full content, modify the intended block with complete context, then use `Write` to replace the file.\n", "- **Verification:** after a fallback write, run the narrowest relevant test or linter command.\n", "\n", "*edit fallback pattern*\n", "```text\n", "1. Attempt Edit against unique anchor text.\n", "2. If the anchor appears multiple times, stop and Read the full file.\n", "3. Identify the intended block by surrounding function/component names.\n", "4. Modify the full file content locally.\n", "5. Use Write to replace the file.\n", "6. Run the smallest relevant verification command.\n", "```\n", "\n", "## 3. Session State Strategy: Resume, Fork, Fresh Start\n", "\n", "Architects must decide which session history best matches the current goal.\n", "\n", "### 3a. Named Resumption\n", "\n", "Use `--resume \u003csession-name\u003e` to continue a specific investigation thread across work sessions. Name sessions by outcome, not by date.\n", "\n", "```bash\n", "claude --session-name auth-invalid-token-investigation\n", "claude --resume auth-invalid-token-investigation\n", "```\n", "\n", "### 3b. Fork-Based Exploration\n", "\n", "Use `fork_session` to create independent branches from a shared analysis baseline. This is ideal for comparing two refactoring approaches or two testing strategies without losing the initial setup.\n", "\n", "```bash\n", "# After shared discovery identifies the auth flow:\n", "/fork auth-fix-centralize-token-validation\n", "/fork auth-fix-wrapper-boundary-checks\n", "\n", "claude --resume auth-fix-centralize-token-validation\n", "claude --resume auth-fix-wrapper-boundary-checks\n", "```\n", "\n", "### 3c. Fresh-Start Rebuild\n", "\n", "When a session is filled with stale tool results, dead-end exploration, or old assumptions, start a new session. The first message should be a handoff summary that re-grounds the model efficiently.\n", "\n", "```handoff summary\n", "Current state:\n", "- \"Invalid Token\" is raised in auth/token.ts by validateAccessToken.\n", "- The login route calls validateAccessToken directly; API middleware calls it through requireAuth.\n", "- Decision: preserve public API shape and fix validation at the shared boundary.\n", "\n", "Next step:\n", "Add the missing issuer check and run the auth middleware test file.\n", "```\n", "\n", "\u003e **Tip.** Architect Tip for the Exam\n", "Decision rule: **resume** when the prior context is still accurate; **fork** when comparing divergent approaches from one shared baseline; **fresh-start** when stale context would mislead the next implementation step.\n", "\n", "## 4. Repository Governance\n", "\n", "Persistent instructions provide universal standards without bloating every prompt.\n", "\n", "- **User-level settings (`~/`) are not shared.** They are useful for personal defaults, not team standards.\n", "- **Project-level `CLAUDE.md`** is the primary vehicle for repository-wide team standards.\n", "- **Directory-level `CLAUDE.md`** scopes rules to one subtree when a package or app has different conventions.\n", "- **Path-scoped rules** in `.claude/rules/` use glob patterns in YAML frontmatter to load conventions only when matching files are edited.\n", "\n", "*.claude/rules/test-conventions.md*\n", "```markdown\n", "# Test File Conventions\n", "- Use existing fixtures before creating new mocks.\n", "- Prefer user-visible assertions over implementation details.\n", "- Run the nearest test file after modifying test helpers.\n", "```\n", "\n", "\u003e **Tip.** Architect Tip\n", "Path-scoped rules are ideal for cross-cutting conventions like `**/*.test.tsx` because they apply by file pattern rather than directory boundary.\n", "\n", "### 4a. Advanced Configuration: Modular Memory\n", "\n", "Large repositories should not put every convention into one giant `CLAUDE.md`. Use `@import` to keep instructions modular and reviewable.\n", "\n", "```markdown\n", "# CLAUDE.md\n", "\n", "@import .claude/memory/testing.md\n", "@import .claude/memory/security.md\n", "@import .claude/memory/release-process.md\n", "```\n", "\n", "After editing memory files, run `/memory` in Claude Code to verify which instructions and imported files are loaded for the current working directory.\n", "\n", "## 5. Agent Skills: Progressive Disclosure\n", "\n", "Skills should minimize token load until Claude actually needs the detail. Use the three-level system:\n", "\n", "- **Level 1, frontmatter:** keep `description` focused on *what the skill does* and *when to use it*. This is the trigger text that sits in the system prompt, so vague descriptions waste tokens and reduce selection reliability.\n", "- **Level 2, `SKILL.md` body:** use standard headers such as `Steps`, `Examples`, and `Troubleshooting` so Claude can scan the procedure quickly.\n", "- **Level 3, linked files:** place high-signal supporting docs in `references/` and link to them from `SKILL.md`. Claude should navigate these files only when needed.\n", "\n", "```markdown\n", "---\n", "name: pr-reviewer\n", "description: Use when reviewing pull requests for security, test coverage, and regression risk. Do not use for writing new features.\n", "---\n", "\n", "# PR Reviewer\n", "\n", "## Steps\n", "1. Inspect the diff.\n", "2. Identify correctness, security, and test risks.\n", "3. Return machine-parseable findings.\n", "\n", "## Examples\n", "See references/review-examples.md.\n", "\n", "## Troubleshooting\n", "If the diff is too large, request a narrower file set.\n", "```\n", "\n", "Lab checkpoint: use the `skill-creator` skill to review custom skills for vague descriptions, missing trigger conditions, missing `Steps`, or absent `references/` links.\n", "\n", "### 5a. User-Scoped Skill Variants\n", "\n", "Team skills belong in the project repository. Personal productivity variants belong in `~/.claude/skills/` with a unique name so they do not alter shared behavior for the team.\n", "\n", "```text\n", "Project skill:\n", ".claude/skills/pr-reviewer/SKILL.md\n", "\n", "Personal variant:\n", "~/.claude/skills/alexa-pr-reviewer/SKILL.md\n", "```\n", "\n", "Use this when you want stricter personal review preferences, local aliases, or private workflow notes without changing the repository standard.\n", "\n", "## 6. The Interview Pattern\n", "\n", "In unfamiliar domains, start by forcing Claude to interview before implementation. The goal is to surface hidden design constraints, such as cache invalidation, failure modes, data retention, or rollout requirements, before code is written.\n", "\n", "```text\n", "Before proposing or implementing a solution, ask 2-3 clarifying questions.\n", "Focus on cache invalidation, failure handling, and compatibility risks.\n", "After I answer, summarize the decision constraints and then implement the smallest viable change.\n", "```\n", "\n", "Use this pattern for ambiguous feature work, domain-specific systems, and changes with reliability implications. Do not use it for tiny, fully specified single-file fixes.\n", "\n", "## 7. Session Context Isolation for CI Review\n", "\n", "The Claude session that generated code is less effective at reviewing it because it carries the same assumptions, exploratory dead ends, and self-justifications that led to the patch. Automated review should use an independent Claude instance with only the diff, repo rules, and review schema.\n", "\n", "For CI/CD, run Claude non-interactively and require machine-parseable output:\n", "\n", "```bash\n", "claude -p \"Review this PR for correctness, security, and missing tests.\" \\\n", " --output-format json \\\n", " --json-schema .claude/schemas/pr-review-findings.schema.json\n", "```\n", "\n", "Use the JSON findings to post inline PR comments. Keep the generation session and the review session isolated.\n", "\n", "## 8. Plan Mode vs. Direct Execution\n", "\n", "Use Plan Mode when the task has architectural implications, multiple implementation approaches, or multi-file modifications. Use direct execution for well-understood, single-file bug fixes with clear scope.\n", "\n", "- **Plan Mode:** suited for refactors, unfamiliar code paths, migration work, and changes where you need to compare approaches before editing.\n", "- **Explore subagent:** during planning, use it to isolate verbose discovery output and return only summaries to the main session, preserving context for decisions.\n", "- **Direct execution:** suited for a narrow bug fix where the target file, expected change, and verification command are already clear.\n", "\n", "```text\n", "Use Plan Mode:\n", "- \"Trace auth token validation and compare two fix approaches.\"\n", "- \"Refactor all checkout tests to a new fixture system.\"\n", "\n", "Use Direct Execution:\n", "- \"Fix this typo in one error message.\"\n", "- \"Add a missing import in this single test file.\"\n", "```\n", "\n", "## Lab Exercise: Incremental Codebase Understanding\n", "\n", "**Objective:** master built-in tool selection and the fallback modification pattern.\n", "\n", "1. **Structural mapping:** use `Glob` to find all configuration files matching `**/*.config.ts`.\n", "2. **Entry point search:** use `Grep` to find every instance of `\"Invalid Token\"` and identify where authentication logic is defined.\n", "3. **Tracing and reading:** use `Read` to inspect the source file found by `Grep`, identify the exported function, then use `Grep` again to find all callers.\n", "4. **The fallback move:** attempt to use `Edit` to add a line where the target anchor text appears multiple times. Observe the failure, then use `Read` to get the full file content and `Write` to replace it reliably.\n", "5. **Divergent approaches:** use `fork_session` to compare two different ways of fixing the authentication bug. Resume each branch to verify the fix.\n", "6. **Skill review:** use the `skill-creator` skill to audit a custom skill for vague descriptions, missing trigger conditions, missing `Steps`, and whether supporting docs belong in `references/`.\n", "7. **Personal skill variant:** create a user-scoped variant in `~/.claude/skills/` with a unique name, then document how it differs from the team skill without changing project files.\n", "8. **Interview pattern:** prompt Claude to ask 2-3 clarifying questions before implementation, specifically probing cache invalidation, failure modes, and compatibility risks.\n", "9. **CI review isolation:** run an independent `claude -p` review with `--output-format json` and `--json-schema`, then map findings to inline PR comments.\n", "\n", "\u003e **Tip.** Architect Tip for the Exam\n", "Tool choice is part of architecture. `Glob` maps structure, `Grep` finds behavior, `Read` builds local understanding, `Edit` handles unique targeted changes, and `Read` + `Write` is the deterministic fallback when targeted matching is ambiguous." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.11.0" } }, "nbformat": 4, "nbformat_minor": 5 }