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. Named Resumption

Use --resume <session-name> to continue a specific investigation thread across work sessions. Name sessions by outcome, not by date.

claude --session-name auth-invalid-token-investigation
claude --resume auth-invalid-token-investigation

3b. Fork-Based Exploration

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.

# After shared discovery identifies the auth flow:
/fork auth-fix-centralize-token-validation
/fork auth-fix-wrapper-boundary-checks

claude --resume auth-fix-centralize-token-validation
claude --resume auth-fix-wrapper-boundary-checks

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. 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.
---

# 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.

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

5a. User-Scoped Skill Variants

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.

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.

6. 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.

7. 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.

8. 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.

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 fork_session to compare two different ways of fixing the authentication bug. Resume each branch to verify the fix.
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.