Claude Code & Skills

1. Navigating Unfamiliar Codebases

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.

• 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.
• Content-based search: use Grep to locate function entry points, exported names, error messages, and constants across the codebase.
• Flow tracing: identify an exported name with Read, then use Grep to find all callers and trace usage through wrapper modules.
• Targeted reading: use Read only after Glob or Grep has narrowed the candidate files.

Goal: understand an authentication failure without flooding context.

1. Glob: "**/*.config.ts" to map configuration files.
2. Grep: "Invalid Token" to locate the error source.
3. Read: inspect the matching source file and identify the exported function.
4. Grep: search for that exported function to find all callers.
5. Read: inspect only the caller files needed to understand the flow.

2. Reliable Modifications

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.

• The Edit tool: preferred for targeted changes using unique text matching. It is more token-efficient and lower risk than full-file writes.
• 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.
• Verification: after a fallback write, run the narrowest relevant test or linter command.

1. Attempt Edit against unique anchor text.
2. If the anchor appears multiple times, stop and Read the full file.
3. Identify the intended block by surrounding function/component names.
4. Modify the full file content locally.
5. Use Write to replace the file.
6. Run the smallest relevant verification command.

3. Session State Strategy: Resume, Fork, Fresh Start

Architects must decide which session history best matches the current goal.

3a. Resuming Sessions

Use claude --resume <session-id> to continue a specific investigation thread across work sessions. Running claude --resume with no argument opens an interactive session picker so you can choose which past session to continue.

# Resume a specific session by its ID
claude --resume 550e8400-e29b-41d4-a716-446655440000

# No argument: opens an interactive picker of recent sessions
claude --resume

3b. Fork-Based Exploration

Use claude --resume <session-id> --fork-session to create independent branches from a shared analysis baseline. Each fork gets its own new session ID, leaving the original untouched. This is ideal for comparing two refactoring approaches or two testing strategies without losing the initial setup. In the Agent SDK, the equivalent option is forkSession.

# After shared discovery identifies the auth flow, fork the
# baseline session twice -- each fork gets its own session ID:
claude --resume 550e8400-e29b-41d4-a716-446655440000 --fork-session
claude --resume 550e8400-e29b-41d4-a716-446655440000 --fork-session

# Agent SDK equivalent: pass forkSession: true when resuming.

3c. Fresh-Start Rebuild

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.

Current state:
- "Invalid Token" is raised in auth/token.ts by validateAccessToken.
- The login route calls validateAccessToken directly; API middleware calls it through requireAuth.
- Decision: preserve public API shape and fix validation at the shared boundary.

Next step:
Add the missing issuer check and run the auth middleware test file.

4. Repository Governance

Persistent instructions provide universal standards without bloating every prompt.

• User-level settings (~/) are not shared. They are useful for personal defaults, not team standards.
• Project-level CLAUDE.md is the primary vehicle for repository-wide team standards.
• Directory-level CLAUDE.md scopes rules to one subtree when a package or app has different conventions.
• Path-scoped rules in .claude/rules/ use glob patterns in YAML frontmatter to load conventions only when matching files are edited.

---
paths: ["**/*.test.tsx"]
---
# Test File Conventions
- Use existing fixtures before creating new mocks.
- Prefer user-visible assertions over implementation details.
- Run the nearest test file after modifying test helpers.

4a. Advanced Configuration: Modular Memory

Large repositories should not put every convention into one giant CLAUDE.md. Use @import to keep instructions modular and reviewable.

# CLAUDE.md

@import .claude/memory/testing.md
@import .claude/memory/security.md
@import .claude/memory/release-process.md

After editing memory files, run /memory in Claude Code to verify which instructions and imported files are loaded for the current working directory.

5. Slash Commands: Project vs. Personal Scope

Slash commands are reusable prompts invoked by name. Where the command file lives determines who can use it.

• Project-scoped commands (.claude/commands/): committed to version control and shared with the whole team. A file named review.md in this directory becomes the team's /review command, carrying the team's review checklist prompt.
• Personal commands (~/.claude/commands/): available in every project on your machine but never shared with teammates.

Review the current diff against our team standards:
1. Security: input validation, authorization checks, secret handling.
2. Tests: new behavior has coverage; no skipped or deleted tests.
3. Regressions: public API shape and error contracts are unchanged.
Report findings as a numbered list with file paths.

6. Agent Skills: Progressive Disclosure

Skills should minimize token load until Claude actually needs the detail. Use the three-level system:

• Level 1, frontmatter: keep description focused on what the skill does and when to use it. This trigger text sits in the system prompt.
• Level 2, SKILL.md body: use standard headers such as Steps, Examples, and Troubleshooting.
• Level 3, linked files: place high-signal supporting docs in references/ and link to them from SKILL.md.

---
name: pr-reviewer
description: Use when reviewing pull requests for security, test coverage, and regression risk. Do not use for writing new features.
context: fork
allowed-tools: Read, Grep, Glob
argument-hint: [pr-number-or-branch]
---

# PR Reviewer

## Steps
1. Inspect the diff.
2. Identify correctness, security, and test risks.
3. Return machine-parseable findings.

## Examples
See references/review-examples.md.

## Troubleshooting
If the diff is too large, request a narrower file set.

Three frontmatter keys deserve special attention:

• context: fork: runs the skill in an isolated sub-agent context, so verbose output does not pollute the main conversation. Use this for codebase-analysis or brainstorming skills that generate long intermediate output.
• allowed-tools: restricts which tools the skill may use during execution (for example, limiting a skill to file writes only).
• argument-hint: prompts the developer for the required parameters when the skill is invoked without arguments.

Keep the scoping distinction sharp: skills are on-demand, task-specific capabilities, while CLAUDE.md carries always-loaded universal standards.

Lab checkpoint: use the skill-creator skill to review custom skills for vague descriptions, missing trigger conditions, missing Steps, or absent references/ links.

6a. User-Scoped Skill Variants

Team skills belong in the project repository. Personal productivity variants belong in ~/.claude/skills/ under a different name from the team skill, so they do not alter shared behavior for teammates.

Project skill:
.claude/skills/pr-reviewer/SKILL.md

Personal variant:
~/.claude/skills/alexa-pr-reviewer/SKILL.md

Use this when you want stricter personal review preferences, local aliases, or private workflow notes without changing the repository standard.

7. The Interview Pattern

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.

Before proposing or implementing a solution, ask 2-3 clarifying questions.
Focus on cache invalidation, failure handling, and compatibility risks.
After I answer, summarize the decision constraints and then implement the smallest viable change.

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.

8. Session Context Isolation for CI Review

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.

claude -p "Review this PR for correctness, security, and missing tests." \
  --output-format json \
  --json-schema .claude/schemas/pr-review-findings.schema.json

Use the JSON findings to post inline PR comments. Keep the generation session and the review session isolated.

Deduplicate across runs. When re-running the review after new commits land on the branch, include the prior findings in context and instruct Claude to report only new or still-unaddressed issues, so reviewers are not flooded with duplicates. Likewise, provide the existing test files as context so test generation does not duplicate scenarios that are already covered.

9. Plan Mode vs. Direct Execution

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.

• Plan Mode: suited for refactors, unfamiliar code paths, migration work, and changes where you need to compare approaches before editing.
• Explore subagent: during planning, use it to isolate verbose discovery output and return only summaries to the main session, preserving context for decisions.
• Direct execution: suited for a narrow bug fix where the target file, expected change, and verification command are already clear.
• Context recovery with /compact: when extended exploration fills the context window with verbose discovery output, run /compact to condense the conversation and reduce context usage before continuing implementation.

Use Plan Mode:
- "Trace auth token validation and compare two fix approaches."
- "Refactor all checkout tests to a new fixture system."

Use Direct Execution:
- "Fix this typo in one error message."
- "Add a missing import in this single test file."

Lab Exercise: Incremental Codebase Understanding

Objective: master built-in tool selection and the fallback modification pattern.

1. Structural mapping: use Glob to find all configuration files matching **/*.config.ts.
2. Entry point search: use Grep to find every instance of "Invalid Token" and identify where authentication logic is defined.
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.
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.
5. Divergent approaches: use claude --resume <session-id> --fork-session twice to create two branches from the shared baseline, one per candidate fix for the authentication bug. Resume each forked session to verify its fix independently.
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/.
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.
8. Interview pattern: prompt Claude to ask 2-3 clarifying questions before implementation, specifically probing cache invalidation, failure modes, and compatibility risks.
9. CI review isolation: run an independent claude -p review with --output-format json and --json-schema, then map findings to inline PR comments.