Claude Architect · Lesson

Code Gen & Developer Productivity

CLAUDE.md, plan mode, built-in tools and investigation.

Code Gen & Developer Productivity is a free Claude Architect lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Claude Architect learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Scenario 4: Developer Productivity

This lesson maps to Scenario 4 — Developer Productivity, one of the eight exam scenarios. The architect's job here is to make Claude Code an effective teammate inside a real repository: investigating unfamiliar code, planning changes safely, and persisting team conventions.

Three pillars carry most of the exam weight in this scenario:

CLAUDE.md — durable, shared project memory.
Plan mode — explore and propose before editing.
Built-in tools + incremental investigation — Glob, Grep, Read, Write, Edit, Bash used in a disciplined loop.

Get these decisions right and you'll handle most D3 (Config & Workflows) questions.

The CLAUDE.md Hierarchy

CLAUDE.md is persistent context loaded automatically into every session. There are three scopes, and choosing the right one is a frequent exam decision:

User-level ~/.claude/CLAUDE.md — personal preferences. NOT shared via VCS, so new teammates never see it.
Project-level ./CLAUDE.md or .claude/CLAUDE.md — committed to the repo and shared with the whole team.
Directory-level — scoped to a subtree, loaded when working in that folder.

Rule of thumb: anything every contributor must follow belongs in the project-level file. Putting team conventions only in your user-level file is a classic trap answer.

# Project memory — committed to VCS, shared with the team
# ./CLAUDE.md

## Build
- `yarn build` then run `dist/main.js`

## Conventions
- Use absolute imports from `src/`
- All API errors return structured `{ code, message }`
- Never commit secrets; read from env vars

Modularizing CLAUDE.md with @imports

A monolithic CLAUDE.md grows unwieldy and burns context tokens on every turn. Two mechanisms keep it lean:

@path imports — pull in modular files, e.g. @./standards/coding-style.md, so shared standards live in their own versioned files.
.claude/rules/ files — each carries YAML frontmatter with a paths glob, and loads only when you edit matching files. This saves context versus stuffing everything into one always-loaded CLAUDE.md.

Use rules for narrowly-scoped guidance (e.g. test conventions) that is irrelevant most of the time.

---
# .claude/rules/testing.md
paths:
  - "**/*.test.ts"
  - "**/*.spec.ts"
---

# Loaded ONLY when editing test files
- Use the existing `makeTestClient()` helper
- One assertion concern per `it(...)` block
- Never mock the database; use the in-memory fixture

Editing Memory: /memory and /compact

Two slash commands manage long-lived context:

/memory edits CLAUDE.md directly and persists across sessions — use it to capture a hard-won convention so it's enforced next time.
/compact compresses the current conversation to free context window. Beware: progressive summarization makes numbers, percentages, and dates vague. If exact values matter, keep them verbatim outside the summary rather than relying on /compact.

The exam likes to contrast durable memory (CLAUDE.md) with transient compression (/compact) — they solve different problems.

# Persist a convention into CLAUDE.md (survives future sessions)
/memory

# Compress the running conversation to reclaim context window
/compact

Plan Mode: Explore Before You Edit

Plan mode lets Claude explore the codebase and propose an approach that you approve before any edits land. Reach for it when:

The change is large or touches many files.
There are multiple viable approaches to weigh.
An architectural decision is involved.
You want safe exploration of unfamiliar code first.

For a single-file fix or a clear stack trace, skip plan mode and go straight to direct execution — planning overhead there is wasted. Matching mode to task size is the core decision this scenario tests.

Isolating Discovery with the Explore Subagent

Investigation produces a lot of verbose output — file dumps, search hits, traces — that can crowd the main context window. The Explore subagent isolates that discovery work, returning a distilled summary instead of raw noise.

This is the same principle as a Skill with context: fork: run the messy, token-heavy part in an isolated context so the main session stays focused. Pair plan mode with an explore step for big, unfamiliar changes.

---
# .claude/skills/audit-deps.md
name: audit-deps
description: Scan the repo for outdated/vulnerable dependencies
context: fork          # isolate verbose scan output
allowed-tools: [Bash, Grep, Read]
argument-hint: "[package-name]"
---

Run the dependency audit and report only actionable findings.

The Built-in Tool Set

Claude Code ships a focused set of built-in tools. Knowing what each is FOR is exam-critical:

Glob — find files by pattern, e.g. **/*.test.tsx.
Grep — search file contents.
Read — load a file into context.
Write — create a file.
Edit — a precise, unique-match change.
Bash — run shell commands.

Glob finds files by name/pattern; Grep finds files by what's inside them. Mixing those two up is a common distractor.

# Glob: locate files by pattern
**/*.service.ts

# Grep: search contents across the repo
grep -rn "process_refund" src/

# Bash: run the test suite
yarn test --runInBand

Edit vs Read+Write

Edit performs a precise change by matching a unique string in the file. If the target string is not unique, the edit fails — that's a safety feature, not a bug.

The correct fallback is to Read the file, then Write the full corrected version (or expand the match with more surrounding context to make it unique). Don't force ambiguous edits; that risks changing the wrong occurrence.

Edit is for surgical, unambiguous changes; Read+Write is for broader or ambiguous rewrites.

# Pseudocode of the decision
# 1) Try a unique-match Edit
#    old_string must appear EXACTLY once in the file
# 2) If the match is not unique -> Edit fails
# 3) Fallback: Read the whole file, then Write the corrected version
#    (or add more surrounding lines to old_string to disambiguate)

Incremental Investigation

The exam rewards a disciplined investigation loop rather than dumping the whole repo into context. The canonical pattern:

Grep the entry points (where does this feature start?).
Read the relevant files you found.
Grep for usages of the symbols you discovered.
Read the consumers to understand impact.

This narrows scope step by step and avoids the lost-in-the-middle problem of over-stuffed context. Trim verbose tool output to the relevant fields as you go.

# 1) Find the entry point
grep -rn "router.post('/refund'" src/

# 2) Read the handler file (Read tool)
# 3) Grep usages of the function it calls
grep -rn "processRefund(" src/

# 4) Read each consumer to assess blast radius

Extending Reach with MCP

Built-in tools cover the local filesystem and shell. To reach external systems — a GitHub repo, a database, an issue tracker — connect an MCP server.

Server primitives: Tools (actions), Resources (read-only data like schemas/catalogs), Prompts (templates).
Scope: project .mcp.json (shared in VCS) vs user ~/.claude.json (personal).
Secrets go through env vars like ${GITHUB_TOKEN} — never commit tokens.
Prefer a maintained community MCP server over building a custom one for standard integrations.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

Commands and Skills

Reusable workflows live in two places. .claude/commands/ is the legacy form; .claude/skills/ is the current one. Both follow the same scoping rule:

Project scope (in the repo) — shared with the team via VCS.
User scope (~/.claude/) — personal, not shared.

Skill frontmatter gives you real control: context: fork to isolate verbose output, allowed-tools to restrict capability (least privilege), and argument-hint to document inputs. Package a recurring investigation as a project-scoped skill so the whole team runs it consistently.

---
# .claude/skills/triage-bug.md  (project scope -> shared via VCS)
name: triage-bug
description: Reproduce a bug, locate root cause via incremental investigation
context: fork
allowed-tools: [Grep, Read, Bash]
argument-hint: "<issue-id or stack trace>"
---

Grep entry points, Read suspects, Grep usages, then summarize root cause.

Quick Check: Choosing Your Approach

A scenario question on configuring Claude Code for a developer-productivity workflow.

Recap: Developer Productivity Essentials

Key takeaways for Scenario 4:

CLAUDE.md scope: project-level (VCS-shared) for team rules; user-level is personal and unshared; directory-level for subtrees.
Keep it lean: @path imports modularize, and .claude/rules/ with a paths glob load only when relevant.
/memory persists conventions; /compact compresses but blurs numbers and dates.
Plan mode for large, multi-approach, or architectural changes; direct execution for single-file fixes and clear stack traces. The Explore subagent isolates noisy discovery.
Built-in tools: Glob (find by pattern), Grep (search contents), Read, Write, Edit (unique-match; fall back to Read+Write), Bash. Investigate incrementally: Grep entry points -> Read -> Grep usages -> Read consumers.
MCP extends reach to external systems; prefer community servers, scope via .mcp.json, secrets through env vars.

Match the tool and mode to the task, and let durable config do the remembering.

Frequently asked questions

Is the “Code Gen & Developer Productivity” lesson free?

Yes — the full text of “Code Gen & Developer Productivity” is free to read here on the web, and the Claude Architect course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Claude Architect course, upgrade to CoddyKit PRO.

What will I learn in “Code Gen & Developer Productivity”?

CLAUDE.md, plan mode, built-in tools and investigation. You practise Claude Architect with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Claude Architect?

No prior experience is required. Claude Architect on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Code Gen & Developer Productivity” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Claude Architect lesson?

Yes. Every Claude Architect lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Claude Architect