Claude Code: Professional Engineering Workflows
A six-chapter, practical Claude / Claude Code learning path covering project instructions, application boundaries, tests, Git review, extensions and team automation.
- Author
- absequ
- Published
- Updated
- Category
- AI Tools
- AI Tools
- Claude / Claude Code
- learning path
- professional engineering
Six ordered tutorial chapters. Prerequisites: basic programming and Git; the core path starts from tool installation. The professional path assumes you have finished the core path or can demonstrate the same edit–verify–review loop.
Official tool documentation checked on 2026-11-06. Examples are original teaching exercises for a disposable notes project, not instructions to alter the absequ repository. Platform, account, model, privacy and permission controls can change; follow the cited current documentation for your installation.
- Write CLAUDE.md guidance and stage a large task
- Deliver a React-to-service feature with explicit contracts
- Choose unit and integration tests that expose real defects
- Review diffs, protect secrets and prepare a pull request
- Use skills, subagents, hooks and MCP deliberately
- Run bounded automation and control team usage
On this page
1. Write CLAUDE.md guidance and stage a large task
Learning objectives: Create concise durable instructions and divide implementation into independently reviewable decisions.
Prerequisites: Complete Claude / Claude Code Getting Started & Core Workflows, including the notes lab and diff review.
CLAUDE.md gives Claude Code persistent project guidance. It can describe architecture choices, validation commands and approval rules that are not obvious from the files. It is not a secret store or a security boundary. Current versions also document conditional AGENTS.md support; repositories with both should inspect the actual loading behavior rather than assuming the same instructions are merged everywhere.
Separate persistent rules from a task plan. For a note-search feature, the plan might investigate current filtering, implement one service boundary and then integrate UI behavior. A handoff should include decisions, source references, changed files and checks. Summarizing resolved evidence is usually better than replaying a long transcript.
Practice in order:
- In a lab checkout, draft the short instruction file below. Replace example checks with actual repository commands before using it with a team.
- Ask Claude to state which instruction files apply and propose a phased plan. Resolve API/storage ambiguity before authorizing edits.
- After each phase, review a small diff and save a concise handoff. Start a new task when changing objectives, supplying only the relevant decisions and evidence.
# CLAUDE.md — notes lab example
Use node:test; avoid new dependencies for small changes.
Preserve unrelated edits. Ask before changing public APIs or persistence.
Never read credential files or log user submissions.
For notes-function changes, run node --test notes.test.mjs.
Report actual checks and unverified behavior separately.Expected outcome: Claude describes applicable guidance and a sequence whose first step is safe to implement. A teammate can use the handoff to resume without discovering an unstated migration decision halfway through the code.
Common mistakes and troubleshooting: Instruction imports and large memory files consume context too. If behavior contradicts guidance, inspect loading and competing instructions instead of adding the same paragraph repeatedly. Put hard tool restrictions in permission settings, not only prose.
Summary: You have durable project expectations and a bounded plan. Next apply them across a frontend and service boundary.
2. Deliver a React-to-service feature with explicit contracts
Learning objectives: Use Claude Code for a vertical feature without turning UI work into an unapproved database or cloud migration.
Prerequisites: Complete chapter 1: Write CLAUDE.md guidance and stage a large task.
A small vertical slice connects a user interaction to a server contract. For a note filter, the UI needs a labelled field, loading/empty/error states and stable keyboard focus. A Node route needs bounded input and consistent response semantics. Persistence stays behind an existing adapter; cloud resource creation and schema migration are separate decisions with cost and rollback implications.
Claude can help locate consumers and implement coordinated edits, but you must specify where sensitive operations belong. In Next.js, keep credentials and Node-only modules on the server side. Browser validation improves feedback but does not protect a public endpoint. A fixture database in a test is not evidence that production persistence is configured.
Practice in order:
- Ask for a read-only impact map from the existing React component through the API type to the storage adapter. Require a list of assumptions before implementation.
- Approve one slice with a fixture-backed UI and a bounded API query. Request accessibility and cancellation behavior explicitly, without adding a new framework.
- Review a component check and a route integration check. Inspect error status, malformed input and empty results separately; defer infrastructure work until its design and owner are agreed.
Implement note-title filtering through the existing UI and Node route.
Preserve response types and the storage adapter. Label the field; keep focus;
show empty and failure states distinctly. Reject queries over 100 characters
on the server. Use test fixtures, not real data. No auth/database/cloud or
dependency changes. Propose consumer checks before editing.// Contract examples for the existing route integration test:
const accepted = { query: 'meeting', expectedStatus: 200 };
const rejected = { query: 'x'.repeat(101), expectedStatus: 400 };
// Assert that the rejected request never calls the storage adapter.
// Send each through the actual route harness used by your project.These fixtures distinguish a bounded valid query from oversized input. They are inputs for your existing route harness, not a claim that a named HTTP endpoint or test API already exists. Also test that an empty result is 200 with an empty list, while storage failure follows the service error contract.
Expected outcome: The diff preserves a clear trust boundary and predictable error contract. You can trace which validation is user feedback and which is authoritative, and there is no new production resource hidden inside a feature patch.
Common mistakes and troubleshooting: If generated code imports a secret helper into a client component, fix the boundary rather than masking the type error. A successful mocked UI check does not validate the actual service route or a production database migration.
Summary: You can review a coordinated application feature. Next build evidence for debugging and behavior-preserving refactoring.
3. Choose unit and integration tests that expose real defects
Learning objectives: Use a failure hypothesis to guide tests and keep refactoring distinct from changing external behavior.
Prerequisites: Complete chapter 2: Deliver a React-to-service feature with explicit contracts.
A pure validation function can be unit-tested; a route integration test should exercise real parsing and the adapter boundary. Ask which defect the new assertion would catch. When both the implementation and mock encode the same mistake, a green suite can still leave the system broken.
For an out-of-order search bug, describe a timing sequence: A starts, B starts, B completes, A completes. The requirement is that B remains visible. Let the test control response completion rather than relying on a sleep. Then request a minimal fix for cancellation or response identity, keeping API semantics and unrelated UI state unchanged.
Practice in order:
- Have Claude inspect the existing test framework and choose the narrowest meaningful regression case. Do not allow it to install a runner solely for this exercise.
- Review the failing case on old behavior before accepting the fix. Add a failure path for the latest request so cancellation does not hide useful errors.
- Rerun the focused test and nearby affected checks. Ask whether the changed interface warrants a wider integration/type/build check, and document any deferred verification.
Create a deterministic regression test for stale search results: request A
starts first but resolves last. The displayed result must remain B.
Use deferred promises in the existing test framework. Explain what assertion
fails before fixing code. Do not rename unrelated modules or weaken checks.Expected outcome: The regression case demonstrates a real defect and passes after the correction. You can explain why a unit test is enough for one function and why another change needs a route or component integration check.
Common mistakes and troubleshooting: Refactors can accidentally change error messages, mutation behavior or sorting. Capture those contracts first. Distinguish sandbox/network launch failures from assertion failures; repeatedly rerunning an unchanged green suite does not increase confidence indefinitely.
Summary: Your test selection now follows risk and evidence. Next turn the code into a reviewable Git change.
4. Review diffs, protect secrets and prepare a pull request
Learning objectives: Make AI edits auditable and preserve a safe recovery path before committing or publishing.
Prerequisites: Complete chapter 3: Choose unit and integration tests that expose real defects.
Claude Code can operate Git tools, but authorization should be explicit. A local branch isolates a history line, not a database or a teammate editing the same checkout. Record the baseline and keep staging/commits/pushes under your team workflow. Review every new file, since an untracked secret-bearing file can be missed by ordinary diff output.
A code review should look for observable failures: invalid-input bypass, unhandled promise rejection, unsafe HTML, secret imports across a client boundary and logging of credentials or personal data. Ask for evidence and severity, then reproduce important findings. A generated approval is not a substitute for ownership of the change.
Practice in order:
- In a clean learning checkout, create a task branch and request no Git mutations from Claude until you approve the patch.
- Inspect changes and untracked files, run the whitespace check and review the focused verification evidence. Have Claude summarize risks rather than merely restate changed lines.
- Prepare a PR description describing the user-visible result and checks. If reverting an incorrect edit, compare and restore only reviewed hunks; do not reset or discard unrelated work.
git status --short
git switch -c tutorial/claude-note-filter
git diff --stat
git diff
git diff --check
# Open untracked files separately.
# A later commit/push needs the team approval appropriate to that action.Expected outcome: A reviewer can assess the final behavior without reading the AI conversation. Secrets are excluded from candidate additions, and incomplete checks are stated plainly instead of hidden behind a generic tested claim.
Common mistakes and troubleshooting: Git ignore rules do not stop tool reads. Use permissions and isolated environments to reduce secret exposure, and sanitize failure output before sharing it. A restore feature may affect more files than expected; inspect its scope and preserve manual changes first.
Summary: The patch is ready for a human decision. Next add reusable procedures and external tools without granting blanket trust.
5. Use skills, subagents, hooks and MCP deliberately
Learning objectives: Distinguish reusable instructions from executable extensions and delegate only independent work.
Prerequisites: Complete chapter 4: Review diffs, protect secrets and prepare a pull request.
Claude Code skills can package instructions and supporting files; their commands are not the same thing as a terminal shell command. A project skill in .claude/skills/<name>/SKILL.md can describe a review routine. Subagents provide separate task context. Hooks run at documented lifecycle events and can execute local code, while MCP adds external tools. Enabling one does not justify enabling all four.
Start with an instruction-only skill and a read-only investigation subagent. Add hooks only after you can state the event, input, output and failure behavior. Test a hook with harmless fixtures before giving it file or network access. For MCP, approve the server and the data scope as you would any integration; tool results can carry untrusted instructions.
Practice in order:
- Draft the skill below in a lab project and check the official discovery/invocation rules for your version. Keep it free of secrets and automatic publishing.
- Ask a subagent to inspect tests while the main session plans a patch. Give it explicit read-only ownership and require file-based findings. For two editing sessions, use separate worktrees and integrate sequentially.
- Design a proposed hook or MCP lookup on paper: what triggers it, which credentials it needs and what happens on failure. Do not connect production data as the first experiment.
---
name: review-note-diff
description: Review a notes-function diff for contract and test risks.
---
Read the diff and affected callers. Report evidenced regressions and missing
boundary tests. Do not change files, send messages, stage, commit or push.
Separate confirmed defects from questions that require execution.Expected outcome: You have one inspectable procedure and a clear reason for any additional capability. Parallel research returns a concise result; workers are not simultaneously rewriting a shared API contract.
Common mistakes and troubleshooting: A hook is executable software, not harmless documentation. Avoid copying a hook configuration without verifying its current event schema and blocking semantics. More subagents also consume context and budget; a small local task may be faster in one session.
Summary: You can extend Claude Code with bounded trust. Next run repeatable work in a team/CI environment and manage its operational cost.
6. Run bounded automation and control team usage
Learning objectives: Use a non-interactive CLI task while preserving approval, credential and budget boundaries.
Prerequisites: Complete chapter 5: Use skills, subagents, hooks and MCP deliberately.
claude -p accepts a prompt and exits, making it useful for controlled scripts. Begin with a report, not an autonomous deployment. A script needs an output contract and a failure policy; a plausible paragraph on stdout is not proof that checks passed. Authentication/provider setup and available features depend on the account and managed settings.
Team use requires an owner for spend, privacy, retention and generated patches. Usage dashboards and current cost documentation are the authority for plan limits; this tutorial does not promise a fixed quota. Reduce waste by scoping files, summarizing resolved context, reusing actual check evidence and avoiding duplicate parallel work. Do not send secrets or customer records merely to make a report more detailed.
Practice in order:
- Try the read-only report command in a disposable checkout with restrictive permissions configured. Verify current CLI help before using flags in a shared script.
- For CI, use an approved service identity and avoid giving untrusted pull requests privileged tokens or a network path to production. Put time/usage limits and human review outside the model output.
- Track representative tasks: time to a reviewed patch, failed checks, unnecessary commands and usage. For an error, distinguish quota, provider authentication, permission and application failures before retrying.
claude -p "Read-only: summarize the note-filter diff and identify missing behavioral checks. Do not edit files, run commands, contact services or publish anything."
# Enforce intended tool permissions in the runner/settings too.
# Inspect output before treating the report as a trusted pipeline artifact.Expected outcome: The script produces a reviewable report with an accountable owner and no implicit publish step. A usage increase leads to investigation of context and repeated work, not an immediate assumption that a more expensive model is necessary.
Common mistakes and troubleshooting: Headless runs cannot depend on a person noticing every prompt. Avoid permission bypass as a workaround for blocked automation. Usage/cost output and event logs may contain sensitive context; define what is retained and who can read it before collecting a large archive.
Summary: You have completed Claude Code from first setup through team automation. Return to the tool overview or compare the Cursor editor workflow next.
References
Project instructions and memory — Anthropic
Claude Code best practices — Anthropic
Claude Code permissions — Anthropic
Claude Code skills — Anthropic
Claude Code subagents — Anthropic
Claude Code hooks — Anthropic
Claude Code MCP — Anthropic
Claude Code CLI reference — Anthropic
Managing Claude Code costs — Anthropic