Claude Code for Learning Codebases: Project Navigation, Architecture Mapping, Execution Tracing, Explanations, and Developer Onboarding

Claude Code can operate as an interactive guide to an unfamiliar repository because it can inspect source files, search symbols and text, follow references, read tests and configuration, examine Git history, run approved commands, and explain the relationships it discovers while the engineer remains inside the development environment.

Its strongest onboarding role is not to generate one definitive summary of the entire codebase, because a large repository contains static structure, runtime behavior, historical compromises, deployment conditions, external integrations, and undocumented institutional knowledge that cannot be represented reliably in one pass.

A more defensible process moves from product orientation into repository structure, domain vocabulary, component boundaries, execution paths, data ownership, tests, configuration, history, and runtime evidence, while every material architectural statement remains connected with the files, symbols, or commands that support it.

Claude Code can reduce the time experienced engineers spend answering routine navigation questions, although maintainers remain necessary when the explanation depends on product intent, ownership, operational incidents, compatibility commitments, or decisions that were never recorded in the repository.

·····

Codebase learning works best as a progressive investigation rather than a one-time repository summary.

A new engineer frequently begins with broad questions about what the system does, which technologies it uses, where execution begins, and how the source tree is organized, although those questions provide only an orientation layer rather than a complete architectural understanding.

The next stage connects product concepts with packages, modules, services, commands, routes, event handlers, databases, external APIs, and tests, after which one concrete scenario can be followed from its initiating action through every material component and side effect.

Later investigation can examine why a design appears unusual, how the implementation changed over time, which constraints are formal contracts, and where the code reflects historical migration rather than current architectural preference.

The resulting knowledge should remain provisional until it has been checked against several evidence classes, because a coherent explanation generated from a small group of obvious files may omit alternative flows, runtime configuration, dynamic dispatch, or production behavior.

........

A Progressive Codebase-Learning Sequence.

Stage	Claude Code Activity	Expected Result
Orientation	Reads top-level files and project metadata	Product purpose, technologies, entry points, and repository layout
Vocabulary	Searches domain types, names, and documentation	Project glossary
Component mapping	Identifies packages, services, modules, and boundaries	Component inventory
Flow tracing	Follows calls, events, state, and integrations	End-to-end execution explanation
Contract review	Reads interfaces, schemas, tests, and public APIs	Behavioral contracts and invariants
Historical review	Examines commits and previous implementations	Likely design rationale
Runtime verification	Runs approved read-only commands or tests	Confirmation or contradiction of static analysis
Knowledge capture	Produces reviewed notes, diagrams, and instructions	Maintained onboarding material
Application	Supports one small real task	Demonstrated independent understanding

·····

Claude Code learns a repository through an agentic exploration loop.

The system gathers context, takes an investigative action, observes the result, and changes its next step according to the evidence, which makes repository learning an iterative process rather than a fixed document-generation operation.

An investigative action may consist of listing directories, reading a package manifest, locating a symbol, finding its references, inspecting an interface, examining a migration, comparing implementation with tests, or running a harmless command that reveals how the project is built.

The model does not need every potentially relevant file attached manually, because it can search and read the repository as questions arise, while explicit file references and selected code help narrow the investigation when the engineer already knows where uncertainty exists.

This flexibility creates the possibility of broad, expensive, and unfocused exploration, so the user should define the learning objective and require Claude to explain which evidence it inspected and which areas remain outside scope.

........

The Investigative Claude Code Loop.

Stage	Investigative Action	Evidence Produced
Ask	Defines one architectural or behavioral question	Clear learning objective
Locate	Searches files, symbols, tests, and history	Candidate evidence
Read	Inspects relevant implementation and configuration	Local understanding
Connect	Traces relationships among files and components	Structural explanation
Verify	Compares with tests, commands, logs, or runtime behavior	Confirmed or contradicted claim
Explain	Produces a level-appropriate account	Transferable understanding
Challenge	Identifies missing paths and alternative interpretations	Residual uncertainty
Preserve	Records reviewed findings in maintained artifacts	Reusable onboarding knowledge

·····

A new engineer should begin with the product and runtime shape before examining individual functions.

Starting from one unfamiliar method can explain what a few lines do without revealing why the code exists, where the behavior begins, which user action it serves, or which other components depend on it.

The first repository overview should establish whether the system is a service, library, command-line application, web application, mobile product, background worker, monorepo, or combination of several deployable units.

It should then identify the principal languages, frameworks, build tools, runtime entry points, test organization, persistence technologies, external services, and infrastructure definitions that shape development work.

The overview should attach paths to each conclusion and label the areas that have not yet been inspected, preventing a partial first pass from becoming an authoritative architectural description.

........

First-Pass Orientation Questions.

Orientation Category	Question to Resolve
Product purpose	Which user or business problem does the system address?
Runtime shape	Which applications, services, workers, libraries, or clients run?
Languages	Which languages define the main implementation?
Frameworks	Which frameworks control routing, state, persistence, or interfaces?
Entry points	Where do startup and user-triggered execution begin?
Repository layout	Where are owned source, tests, infrastructure, generated code, and documentation?
Build system	How is the project installed, compiled, tested, and packaged?
Data layer	Which schemas, models, migrations, and repositories govern persistence?
External systems	Which APIs, queues, storage systems, and identity providers are used?
Deployment	How do artifacts reach runtime environments?
Ownership	Which teams or packages control major responsibilities?
Observability	Where are logs, metrics, traces, and alerts produced?

·····

The repository map should distinguish deployable applications from libraries, tooling, generated artifacts, and infrastructure.

Large source trees often contain several categories that look equivalent when viewed only as folders, although they play substantially different operational roles.

One directory may contain a public service, another a shared domain library, another generated clients, another deployment manifests, while a final directory contains tests that encode behavior more precisely than the documentation.

Claude should classify the principal directories by responsibility and indicate which are edited by developers, generated automatically, vendored from another source, or maintained by infrastructure tooling.

This classification prevents new engineers from spending time reading code that the team does not own or modifying files that will be overwritten during the next build.

........

Repository-Map Categories.

Directory Category	Onboarding Significance
Deployable application	Runs independently in an environment
Shared library	Supplies reusable behavior to other packages
Domain module	Encodes business concepts and rules
Interface layer	Handles HTTP, CLI, UI, messaging, or external contracts
Persistence layer	Reads and writes durable state
Infrastructure	Defines deployment and runtime resources
Test code	Encodes expected behavior and fixtures
Build tooling	Compiles, packages, or generates artifacts
Generated code	Should ordinarily be changed through its source generator
Vendored dependency	Usually maintained outside the repository
Documentation	Provides declared design and operating procedures
Examples	Demonstrates intended public use

·····

Project vocabulary should be established before architectural explanations become too detailed.

Repositories frequently use product names, abbreviations, legacy terminology, internal identifiers, and domain-specific concepts whose meaning is not obvious from language syntax.

The same word may refer to a database record, external customer concept, event type, user-interface state, or historical product name, while two similar terms may represent intentionally different business rules.

Claude can search type names, comments, schema definitions, tests, documentation, and user-facing text to produce a glossary, although each definition should include the source that supports it and any conflicting usage.

A reviewed glossary reduces repeated confusion during later flow tracing and helps the new engineer ask questions using the terminology maintained by the team.

........

Fields for a Project Glossary.

Glossary Field	Required Content
Term	Exact repository or domain expression
Meaning	Concise definition
Technical representation	Type, table, event, configuration, or module
Product significance	User or business function
Main source	File, schema, or documentation path
Related terms	Similar or dependent concepts
Distinction	How it differs from commonly confused terms
Historical note	Previous name or migration where relevant
Confidence	Confirmed, conventional, inferred, or unresolved

·····

Navigation should begin with a domain concept and move toward files, symbols, and runtime paths.

A request to list every file related to authentication may produce a large collection containing login screens, access checks, token utilities, configuration, test fixtures, and unrelated documentation without showing how they interact.

A more productive sequence begins with one scenario, such as a returning user whose access token has expired, and asks Claude to locate the entry point, validation, refresh process, authorization checks, persistence, external identity calls, and final response.

The concept supplies the semantic target, symbol search identifies implementation, tests show expected behavior, while configuration and runtime evidence reveal which path actually executes.

This movement from concept to evidence is more useful than treating the repository tree as the learning sequence.

........

Navigation Questions That Build an Execution Model.

Question	Expected Evidence
Where does this feature begin?	Route, command, listener, UI action, or scheduled trigger
Which component owns the behavior?	Service, package, module, class, or function
What calls it?	Upstream callers and initiating conditions
What does it call?	Dependencies and downstream effects
Where is state read or changed?	Database, cache, file, event, or external API
Which tests describe it?	Behavioral scenarios and edge cases
Which configuration changes it?	Environment variables, flags, and deployment settings
What happens on failure?	Errors, retries, rollback, and fallbacks
How is it observed?	Logs, metrics, traces, and alerts
Why is it structured this way?	History, compatibility, and repository convention

·····

Language-server navigation provides a structural view that text search cannot reproduce alone.

Claude Code can use language-server capabilities to locate canonical definitions, find references, identify interface implementations, inspect types, follow call hierarchies, and surface diagnostics within supported languages.

One symbol-aware lookup may replace several rounds of searching for a common method name and opening files that happen to contain the same text but do not participate in the relevant execution path.

This becomes especially useful in monorepositories, generic type systems, inheritance hierarchies, overloaded functions, generated interfaces, and dependency-injection structures where textual similarity is an unreliable guide.

Language-server results remain incomplete for reflection, configuration-driven dispatch, template references, SQL, dynamically constructed identifiers, generated runtime behavior, and external integrations, which makes them one evidence layer rather than a complete architectural graph.

........

Language Intelligence and Text Search Serve Different Purposes.

Navigation Method	Strongest Evidence
Go to definition	Canonical symbol declaration or implementation
Find references	Statically recognized consumers
Interface implementations	Concrete realizations of an abstraction
Type inspection	Inputs, outputs, generics, and contracts
Call hierarchy	Statically discoverable callers and callees
Diagnostics	Current type and language errors
Text search	Strings, SQL, templates, flags, and configuration
Repository tree	Package and directory structure
Build output	Generated relationships and dependency failures
Runtime trace	Actual execution under specific conditions

·····

Static navigation should be supplemented with configuration because runtime selection often occurs outside the source path.

Dependency injection, environment variables, feature flags, deployment manifests, plugin registries, service discovery, and conditional imports can determine which implementation runs without making the relationship obvious from direct symbol references.

A service interface may have several implementations while configuration selects only one for a particular environment, or an apparently unused handler may be registered dynamically through metadata.

Claude should inspect the configuration files and startup process that assemble the running application, while architecture explanations should state whether a relationship is always active, environment-dependent, feature-gated, or merely available.

This distinction prevents the static possibility of a code path from being described as the universal runtime behavior.

........

Configuration Sources That Influence Architecture.

Configuration Source	Possible Architectural Effect
Environment variables	Select endpoints, features, credentials, and behavior
Dependency-injection registration	Chooses concrete implementations
Feature flags	Activates alternative paths
Deployment manifests	Changes service topology and resources
Build variants	Include or exclude modules
Plugin registries	Load behavior dynamically
Route configuration	Maps external paths to handlers
Queue bindings	Connect producers and consumers
Database settings	Select storage or migration behavior
Tenant configuration	Changes behavior by customer
Runtime arguments	Select modes and entry points
Secret configuration	Enables external integrations

·····

Tests explain expected behavior more reliably than implementation naming alone.

A function name can suggest what the author intended, although tests show which inputs, outputs, errors, side effects, and boundary conditions the repository currently checks.

Claude can locate unit, integration, end-to-end, snapshot, contract, and fixture-based tests associated with a component, then explain which behaviors are encoded and which important paths appear untested.

Tests may themselves be incomplete or obsolete, so their presence should be described as evidence of expected behavior rather than proof that every production scenario follows the same contract.

A new engineer should learn the project’s test hierarchy, fixture system, mocking conventions, and required commands because those elements reveal how maintainers expect changes to be validated.

........

Test Evidence for Codebase Learning.

Test Type	Architectural Information
Unit test	Local rules, inputs, outputs, and boundaries
Integration test	Module and infrastructure interactions
End-to-end test	User-visible execution path
Contract test	External or cross-service interface
Snapshot test	Serialized or rendered representation
Property-based test	Invariants across broad inputs
Migration test	Data compatibility and transformation
Performance test	Latency, memory, or throughput expectation
Security test	Authorization, validation, and trust boundaries
Fixture	Representative state and domain assumptions

·····

Git history helps explain why code exists when current structure appears irrational or redundant.

An adapter, duplicated path, unusual error type, defensive check, or legacy name may look unnecessary when read only in its present form.

Commit history, previous implementations, issue references, and blame information may reveal that the design was introduced for backward compatibility, an incident correction, staged migration, customer requirement, or platform limitation.

Claude should distinguish rationale explicitly stated in a commit or issue from an explanation inferred from the sequence of changes, because historical proximity does not prove causation.

When the repository lacks adequate historical evidence, the unresolved question should be directed to a maintainer rather than converted into a confident story.

........

Historical Evidence and Its Strength.

Historical Finding	Evidentiary Status
Commit explicitly describes the rationale	Direct historical evidence
Issue links the change to a defect	Supported incident history
Migration document defines a compatibility period	Formal historical constraint
Similar pattern appears across the repository	Repository convention
Design predates the current architecture	Chronological observation
Change followed a production incident	Possible relationship requiring confirmation
Rationale inferred from code movement	Model inference
Original discussion is unavailable	Institutional knowledge gap

·····

Architecture mapping should separate structure, runtime behavior, data, deployment, security, and observability.

One oversized diagram containing every package, class, database, queue, external system, and deployment resource may appear comprehensive while failing to answer practical questions about responsibility and execution.

A repository map should show source organization, while a component map should identify runtime responsibilities and dependency direction.

Sequence diagrams can represent one request or event path, data maps can identify ownership and transformation, deployment diagrams can show runtime topology, while security and observability maps expose boundaries that ordinary source structure may hide.

Claude can generate Mermaid diagrams, although each diagram should include evidence references, scope, and simplifications before it becomes maintained documentation.

........

Architecture Views for Developer Onboarding.

Architecture View	What It Should Represent
Repository map	Applications, packages, libraries, tests, and infrastructure
Component map	Runtime components and responsibilities
Dependency map	Permitted and actual dependency direction
Request sequence	Entry point, processing, state, and response
Event flow	Producer, broker, consumer, retry, and dead-letter path
Data map	Models, ownership, transformations, and stores
Integration map	External APIs, authentication, and failure boundaries
Deployment map	Artifacts, environments, networks, and dependencies
Security map	Trust boundaries, identities, authorization, and sensitive data
Observability map	Logs, metrics, traces, alerts, and correlation identifiers

·····

Every architecture diagram should state its scope and omissions.

A sequence diagram for password login may not describe social login, token refresh, service accounts, administrative impersonation, or background authorization.

A component map generated from one package may omit an external service whose client is created dynamically, while a deployment map based on local configuration may not represent production routing.

Claude should therefore accompany each diagram with the scenario, environment, files inspected, dynamic relationships inferred, and evidence still requiring runtime or maintainer confirmation.

A diagram becomes safer when its limitations are visible than when visual polish gives a partial interpretation the appearance of a formal specification.

........

Diagram Qualification Fields.

Field	Required Detail
Scope	Feature, package, service, or complete system
Scenario	Exact request, event, or operational path
Environment	Local, test, staging, production, or general
Evidence	Files, configuration, tests, and history inspected
Simplifications	Components or branches intentionally omitted
Dynamic behavior	Relationships inferred from runtime configuration
Unknowns	Evidence not available
Review status	Draft, maintainer-reviewed, or authoritative
Revision date	When the diagram was checked against the repository

·····

End-to-end tracing should follow one concrete scenario in execution order.

Broad questions such as “How does checkout work?” can merge several flows, including new purchases, retries, refunds, guest orders, subscription renewals, and administrative corrections.

A concrete scenario gives Claude a trigger and state from which it can follow entry points, validation, authorization, domain decisions, persistence, integrations, emitted events, and final output.

The trace should identify branches that alter the path and should state whether each relationship was confirmed by source, tests, configuration, or runtime observation.

This method creates a reusable mental model that a new engineer can apply when debugging or modifying the same feature.

........

Fields in an End-to-End Execution Trace.

Trace Field	Required Information
Trigger	User action, request, command, schedule, or event
Initial state	Preconditions and relevant stored data
Entry point	Route, listener, command, or handler
Validation	Schema and business-input checks
Authentication	Identity establishment
Authorization	Permission decision
Dispatch	Selection of component or implementation
Domain logic	Rules and state transitions
Persistence	Reads, writes, transactions, and cache effects
Integrations	External API, storage, or messaging calls
Events	Emitted messages and consumers
Output	Response, document, state, or side effect
Failure paths	Errors, retries, fallback, and rollback
Observability	Logs, metrics, traces, and correlation
Tests	Scenarios that encode the path

·····

Data ownership should be mapped separately from control flow.

A request may pass through several services while only one component owns the authoritative record, another maintains a cache, and a third stores a derived projection.

Without this distinction, a new engineer may update the wrong representation or assume that two tables contain equivalent state.

Claude should identify which component creates, validates, mutates, reads, replicates, or derives each important data object, along with transaction boundaries and consistency expectations.

The explanation should also distinguish source-of-truth data from denormalized views, analytics records, event payloads, caches, and temporary processing state.

........

Fields for a Data-Ownership Map.

Data Field	Architectural Question
Entity or record	What business concept does it represent?
Authoritative owner	Which component controls its lifecycle?
Storage	Where is it persisted?
Creation	Which path creates it?
Mutation	Which components may change it?
Read access	Which consumers depend on it?
Replication	Is it copied into another service or store?
Derived views	Which projections or reports depend on it?
Consistency	Strong, eventual, cached, or batch-updated?
Retention	How long is it stored?
Sensitivity	Does it contain confidential or regulated data?
Migration	How does its schema evolve?

·····

External integration explanations should include failure and retry behavior.

A service calling a payment processor, identity provider, object store, model API, or message broker may appear straightforward along the successful path while operational complexity resides in timeout, retry, idempotency, rate-limit, and partial-failure handling.

Claude should inspect client wrappers, configuration, queue behavior, circuit breakers, retry policies, error translation, and observability around the external boundary.

The onboarding explanation should identify which errors are retried, which are exposed to callers, which operations require idempotency, and whether failure can leave local and remote systems inconsistent.

This operational context is necessary before a new engineer modifies integration code that appears to be a simple function call.

........

External-Integration Review Areas.

Area	Question
Client creation	Where and how is the integration configured?
Authentication	Which credential or identity mechanism is used?
Request contract	Which payload and headers are sent?
Response mapping	How is external output translated internally?
Timeout	How long does the call wait?
Retry	Which errors are retried and how often?
Idempotency	How are duplicate operations prevented?
Rate limiting	How is capacity handled?
Fallback	What happens when the provider is unavailable?
Consistency	Can local and remote state diverge?
Security	Which sensitive values cross the boundary?
Observability	Which logs, metrics, and traces expose the interaction?

·····

Explanations should be requested at the level required by the learner’s current question.

A product-level explanation describes the user behavior enabled by a component, while an architectural explanation describes responsibility and dependency boundaries.

A module-level explanation shows collaboration among files and types, a runtime explanation follows one scenario, while a line-level explanation clarifies syntax, language features, or local invariants.

Historical and operational explanations address different questions again, including why the design evolved and how the behavior appears in deployed environments.

Telling Claude which level is required prevents a new engineer from receiving a detailed walk-through of implementation when the real uncertainty concerns ownership or product purpose.

........

Levels of Codebase Explanation.

Explanation Level	Intended Content
Product	User or business behavior
System	Major applications and external systems
Architectural	Responsibilities and boundaries
Component	One service, package, or subsystem
Module	Collaboration among files and types
Runtime	One scenario in execution order
Function	Inputs, outputs, state, and edge cases
Line	Syntax or local expression
Historical	Evolution and likely rationale
Operational	Deployment, configuration, logs, and failure handling
Security	Trust boundaries and authorization
Performance	Resource use and bottlenecks

·····

Difficult components should be explained through contracts and invariants rather than prose alone.

A large class or module may contain numerous functions whose individual behavior is less important than the state transitions, ownership rules, and assumptions that all methods must preserve.

Claude should identify inputs, outputs, allowed state, prohibited state, side effects, synchronization requirements, and error conditions before describing the implementation line by line.

Tests, types, database constraints, assertions, and validation rules can provide evidence for those invariants.

The learner can then use the invariant model to understand new methods without memorizing every branch.

........

Contract Fields for a Difficult Component.

Contract Field	Required Explanation
Responsibility	Behavior the component owns
Inputs	Accepted data and preconditions
Outputs	Return values, events, and side effects
State	Internal and external state used
Invariants	Conditions that must always hold
Dependencies	Components required
Mutations	State changes performed
Concurrency	Locking, ordering, or atomicity
Errors	Failure categories and propagation
Boundaries	Behavior intentionally outside scope
Tests	Evidence that the contract is encoded
Consumers	Callers relying on the behavior

·····

Claude should distinguish confirmed evidence from architectural inference.

A model can connect partial evidence into a convincing narrative even when it has not inspected every caller, runtime configuration, or deployment environment.

The user should require evidence labels for material claims, including whether a statement is confirmed in source, tests, configuration, runtime output, Git history, or repository convention.

Relationships inferred from naming, proximity, or repeated patterns should remain marked as inferred until another evidence class confirms them.

Unknowns should be preserved explicitly because they identify where a maintainer interview, runtime trace, or additional repository access is required.

........

Evidence Labels for Codebase Explanations.

Evidence Label	Meaning
Confirmed in code	Directly represented in the implementation
Confirmed in tests	Encoded by an existing test
Confirmed in configuration	Defined by current project or deployment settings
Confirmed at runtime	Observed through an approved command, log, or trace
Confirmed in history	Explicitly recorded in a commit, issue, or decision record
Repository convention	Repeated pattern without formal contract
Inferred	Plausible interpretation of incomplete evidence
Unknown	Required evidence was unavailable
Potentially stale	Documentation or memory may no longer match current code
Maintainer-confirmed	Verified through accountable human knowledge

·····

File and symbol references make explanations auditable.

A statement that authorization occurs before a database mutation is substantially more useful when it identifies the handler, authorization function, service method, and relevant test in execution order.

Paths and symbols allow the learner to verify the explanation, reopen the evidence later, and detect when a future refactor makes the documentation stale.

Line ranges can help during focused review, although they may change quickly and should accompany stable symbol names or file sections.

A repository overview without references should be treated as orientation prose rather than as verified technical documentation.

........

Reference Types in a Codebase Explanation.

Reference	Best Use
File path	Locates component or configuration
Symbol	Identifies stable implementation unit
Line range	Supports precise local explanation
Test name	Shows encoded behavioral scenario
Commit	Supports historical rationale
Issue or ADR	Supports formal decision context
Command	Reproduces build or runtime evidence
Log or trace identifier	Supports observed execution
Schema or migration	Supports data behavior
Deployment manifest	Supports runtime topology

·····

Plan Mode is the appropriate default for codebase exploration.

Plan Mode allows Claude to read, search, inspect, and run approved exploratory commands without modifying source files, which separates understanding from implementation.

A new engineer can remain in Plan Mode throughout orientation, architecture mapping, flow tracing, and documentation review because none of those activities requires edits to production code.

The mode also makes command requests more visible when the project contains scripts whose effects are not yet understood.

This boundary reduces accidental changes and discourages the session from moving prematurely from “how does this work?” to “I have refactored it.”

........

When Plan Mode Is Appropriate for Learning.

Situation	Reason
Repository is unfamiliar	Prevents accidental edits
Architecture is being mapped	Keeps investigation read-only
Production or security code is involved	Preserves oversight
Build commands are not understood	Encourages command review
External infrastructure may be referenced	Prevents automatic access
Onboarding documentation is being verified	Separates evidence gathering from writing
Learner is evaluating a first task	Prevents implementation before understanding
Historical behavior is uncertain	Avoids cleanup based on incomplete rationale

·····

Codebase learning should precede architectural criticism.

A new engineer may quickly identify duplicated logic, deep inheritance, large modules, or unusual boundaries and ask Claude how the design should be improved.

The apparent problem may reflect compatibility, performance, migration, ownership, or deployment constraints that have not yet been discovered.

The disciplined sequence describes current behavior, verifies it, identifies explicit constraints, separates deliberate design from accidental complexity, and only then evaluates alternatives.

Claude should not propose a rewrite merely because another pattern is more common in general software literature.

........

A Controlled Sequence From Understanding to Criticism.

Stage	Question
Describe	What does the current system do?
Locate	Where is the behavior implemented?
Verify	Which tests and runtime evidence confirm it?
Constrain	Which compatibility and operational rules apply?
Historicize	Why did the current design evolve?
Separate	Which complexity is deliberate and which appears accidental?
Critique	What limitations follow from the design?
Compare	Which alternatives satisfy the same constraints?
Propose	What change would improve the system?
Validate	How would the change be tested and rolled back?

·····

/init creates a starting repository guide rather than a complete onboarding system.

The command can inspect the repository and generate a starter CLAUDE.md containing build commands, test instructions, project conventions, and other visible operating guidance.

When a repository already contains the file, Claude can suggest improvements rather than replacing the maintained content automatically.

The generated result should be reviewed by engineers who understand unwritten ownership, deployment, compatibility, and product constraints that may not be visible in source.

A useful initialization process identifies high-impact instructions whose absence would cause repeated mistakes while avoiding a large generic manual that consumes context in every session.

........

Appropriate Contents of a Starter CLAUDE.md.

Instruction Category	Example Content
Repository purpose	Concise product and system description
Layout	Major directories and responsibilities
Build	Exact installation and compilation commands
Tests	Focused and complete validation commands
Style	Non-obvious conventions
Architecture	Dependency and ownership boundaries
Compatibility	Supported runtimes and public promises
Generated files	Paths that should not be edited manually
Environment	Required local services and configuration
Safety	Commands and systems requiring approval
Completion	Checks required before claiming success

·····

CLAUDE.md can assist human onboarding when it remains concise, reviewed, and versioned.

The file gives Claude persistent project context while also offering new engineers a compact description of repository commands, architecture rules, and recurring pitfalls.

Its ideal brevity makes it unsuitable as the only onboarding artifact, because a complete learning program may also require diagrams, tutorials, runbooks, decision records, ownership maps, and guided first tasks.

Changes to architecture or build processes should trigger review of CLAUDE.md, while proposed updates should receive the same scrutiny as other maintained documentation.

A stale instruction can mislead both the model and every engineer who uses the file as a trusted starting point.

........

What Belongs in CLAUDE.md and What Belongs Elsewhere.

Suitable for CLAUDE.md	Better Stored Elsewhere
Build and test commands	Full architecture tutorial
Repository layout	File-by-file inventory
Non-obvious conventions	Frequently changing project status
Supported environments	Complete API documentation
Architectural boundaries	Detailed operational runbook
Required validation	Historical incident narrative
Common environment pitfalls	Temporary branch instructions
Safety restrictions	Long training exercises
Ownership contact pattern	Full organization directory

·····

Nested instructions make large repositories easier to explore without loading every local convention at once.

A monorepo may contain frontend, backend, infrastructure, data, mobile, and shared packages whose build commands and architectural rules differ substantially.

A root CLAUDE.md can describe repository-wide structure and policies, while subdirectory files provide package-specific commands, terminology, and constraints when Claude works in that area.

Starting the session at the repository root exposes broad access and root instructions, while starting inside one subsystem narrows the initial scope and reduces irrelevant file reads.

This layered approach helps onboarding proceed by area rather than requiring one enormous instruction file that attempts to describe every package continuously.

........

Large-Repository Scoping Controls.

Control	Function
Root CLAUDE.md	Defines repository-wide structure and rules
Nested CLAUDE.md	Adds subsystem-specific guidance
Path-scoped rules	Loads instructions for matching files
Starting directory	Defines initial access and context
Read deny rules	Excludes generated, vendor, or irrelevant paths
Sparse worktree	Checks out selected repository areas
--add-dir	Adds another directory deliberately
Code-intelligence plugin	Navigates symbols without broad reading
Per-area skills	Loads local procedures only when needed
Separate sessions	Isolates investigations by subsystem

·····

Starting location should reflect the learning objective.

An engineer seeking a complete system overview should begin at the repository root, where Claude can inspect top-level instructions, applications, shared packages, and infrastructure.

Someone onboarding to one service may begin inside that service, reducing irrelevant context while retaining inherited repository instructions from parent directories.

Cross-service flows may later require explicitly adding sibling directories or beginning a separate root-level session.

The chosen starting point therefore shapes both what Claude can see initially and which instructions guide its interpretation.

........

Starting-Directory Choices.

Learning Objective	Suggested Starting Location
Complete repository orientation	Repository root
One service or package	Subsystem root
Frontend feature	Relevant application directory
Shared library	Library package
Cross-service request	Repository root or selected added directories
Infrastructure deployment	Infrastructure directory with application references
Historical investigation	Repository root with Git access
Narrow first task	Smallest directory containing the complete affected path

·····

Subagents can investigate separate architectural concerns without filling the primary context.

A subagent receives its own context, tools, and instructions, allowing it to inspect a broad area and return a compressed result to the main session.

An architecture explorer may map packages and dependencies, while separate agents examine data, tests, operations, security, and history.

The primary conversation can then compare their findings and preserve its context for synthesis, learner questions, and verification.

Subagent conclusions should retain evidence references, while disagreements should remain visible rather than being merged into one artificially consistent account.

........

Possible Explorer Subagents.

Subagent	Investigation
Architecture explorer	Packages, dependencies, and public boundaries
Request-flow explorer	One end-to-end runtime scenario
Data explorer	Schemas, migrations, ownership, and consistency
Test explorer	Frameworks, fixtures, coverage, and missing paths
Operations explorer	Build, deployment, configuration, logs, and metrics
Security explorer	Identity, authorization, secrets, and trust boundaries
History explorer	Migrations, incidents, and design evolution
Terminology explorer	Domain vocabulary and project-specific names
Dependency explorer	Internal and external package relationships
Documentation reviewer	Staleness and contradiction across maintained guides

·····

Subagent work should be divided by question rather than by arbitrary directory alone.

One package may participate in authentication, billing, and audit flows, while one architectural question may span several directories.

Assigning a subagent to “read the services folder” can create a broad inventory without answering a meaningful onboarding question.

A stronger assignment asks one agent to trace token refresh, another to map identity storage, and another to examine authorization tests and failure handling.

Question-based scopes produce findings that can be compared directly with the engineer’s learning objective.

........

Elements of a Useful Explorer Assignment.

Assignment Element	Required Detail
Question	Exact architectural issue
Scope	Directories, services, or evidence classes
Exclusions	Areas intentionally omitted
Evidence	Files, symbols, tests, history, or commands required
Output	Map, trace, glossary, or risk list
Confidence labels	Confirmed, inferred, and unknown
Stop condition	Point at which further access or human knowledge is required
References	Paths and symbols supporting conclusions

·····

Context management is necessary because every file read and tool result competes for attention.

Claude Code’s active context contains project instructions, memory, conversation history, source files, command output, and subagent results.

A long onboarding session can gradually fill with outdated hypotheses, repeated file contents, and details from unrelated components, making later explanations less focused.

The engineer can inspect context use, compact prior work around a chosen subject, clear the conversation for a new question, branch into an alternative interpretation, or resume a named investigation later.

Verified discoveries should be moved into maintained documentation rather than preserved only inside a conversation that may eventually be summarized or discarded.

........

Context-Management Commands for Onboarding.

Command	Learning Use
/context	Inspect what occupies the active context
/compact	Summarize earlier investigation
/compact focus on architecture	Preserve selected findings
/clear	Begin a new question with project context retained
/branch	Explore a competing interpretation
/resume	Continue a saved investigation
/rename	Give the session a discoverable title
/btw	Ask a small side question without expanding the main history
/export	Save a readable investigation transcript
/memory	Inspect persistent project knowledge

·····

Compaction should preserve confirmed findings and discard failed investigative paths.

A long session may include several guesses about component ownership or execution behavior before the correct path is found.

An uncontrolled summary may preserve the final conclusion while losing its evidence, or may retain an earlier false assumption because it appeared repeatedly in the conversation.

Before compaction, the engineer should ask Claude to summarize confirmed architecture, unresolved questions, inspected paths, and rejected hypotheses separately.

Stable repository instructions reload after compaction, although temporary conversational detail may not survive with the same precision.

........

Fields for a Safe Onboarding Compaction.

Compaction Field	Required Content
Confirmed facts	Evidence-backed conclusions
Key references	Files, symbols, tests, and commands
Current architecture map	Working component model
Resolved vocabulary	Agreed definitions
Rejected hypotheses	Interpretations disproved by evidence
Remaining unknowns	Questions requiring further work
Next investigation	Exact continuation point
Maintainer questions	Institutional knowledge still needed
Documentation candidates	Findings ready for review and preservation

·····

Auto memory can preserve useful repository discoveries while also repeating unverified assumptions.

Claude Code can retain build commands, debugging lessons, conventions, and recurring project patterns across separate sessions and worktrees.

A confirmed focused test command or environment requirement may save substantial onboarding time, while a guessed component owner or incorrect explanation of a business rule can mislead every future session.

The learner should inspect memory and remove temporary branch state, failed hypotheses, or conclusions that became obsolete after a migration.

Persistent knowledge should describe its scope and evidence rather than appearing as an unconditional repository truth.

........

Suitable and Unsuitable Auto-Memory Content.

Suitable Memory	Unsuitable Until Verified
Confirmed build command	Guessed ownership
Reliable focused test command	Inferred product requirement
Stable repository convention	One failed debugging hypothesis
Required local service	Temporary branch behavior
Maintainer correction	Assumed production configuration
Recurring environment pitfall	Unreviewed architecture map
Confirmed generated-file rule	Old migration procedure
Stable package relationship	Unverified external-system behavior

·····

IDE integration makes local explanations immediate while potentially narrowing the architectural view.

In VS Code and compatible environments, Claude can receive selected code, file references, and line ranges, allowing the engineer to ask precise questions without copying a complete file into the conversation.

This is useful for generic constraints, decorators, state transitions, query construction, unfamiliar language syntax, and local patterns whose meaning is unclear.

A line-level explanation may still miss the caller, configuration, side effects, and system-level contract, so the user should ask Claude to connect the selection with upstream and downstream behavior where relevant.

Separate conversations can preserve focused inquiries while a broader architecture session remains available for system-level questions.

........

Useful IDE-Based Questions.

Question	Learning Objective
Why is this generic constraint required?	Language and type-system understanding
Which callers depend on nullable behavior?	Contract and compatibility
How does this compare with the repository’s usual pattern?	Convention recognition
Trace this handler back to its route	Upstream navigation
Trace it forward to persistence	Downstream navigation
Which assumptions are enforced elsewhere?	Invariant discovery
Which test covers this branch?	Behavioral evidence
What changes under another feature flag?	Configuration awareness
Why did this line change historically?	Rationale review

·····

Local explanations should be expanded when the selected code crosses an architectural boundary.

A database call, remote request, event publication, authorization check, or cache mutation may look like one expression while triggering behavior that belongs to another component or operational system.

Claude should identify when the selected lines depend on an external contract and offer the surrounding path rather than limiting the explanation to syntax.

The engineer can then decide whether the local question is answered or whether a larger execution trace is necessary.

This prevents code reading from becoming a sequence of disconnected line explanations without a model of the system.

........

Signals That a Local Question Requires Broader Context.

Signal	Broader Investigation
Interface call	Find concrete implementation
Dependency injection	Inspect registration and configuration
Database repository	Trace schema, transaction, and ownership
Event publication	Locate broker and consumers
External client	Inspect contract, timeout, and retry
Authorization helper	Trace identity and policy rules
Feature flag	Compare active and inactive paths
Generated type	Locate source schema or generator
Cache access	Determine consistency and invalidation
Async task	Trace scheduling, retry, and completion

·····

/team-onboarding packages recent Claude Code habits into a shareable starting guide.

The command analyzes how an experienced user has interacted with Claude Code recently, including commands and connected tooling, then produces a Markdown guide that another engineer can use as an initial setup message.

This can transfer real project habits, common commands, and established workflows more effectively than a generic introductory presentation.

The generated guide reflects recorded Claude Code activity rather than every aspect of engineering practice, which means that procedures performed outside Claude, rare incident operations, and undocumented architectural rules may be absent.

Maintainers should review the guide and combine it with formal onboarding artifacts rather than treating recent tool history as a complete description of team practice.

........

What a Generated Team-Onboarding Guide May Capture.

Likely Content	Possible Omission
Frequently used commands	Rare emergency procedures
Common Claude workflows	Work performed outside Claude Code
Connected MCP tools	Informal human coordination
Repeated repository instructions	Unrecorded product history
Typical investigation patterns	Deprecated but still supported paths
Common development tasks	Security or compliance exceptions
Preferred prompts	Institutional ownership knowledge
Recent project activity	Older architectural rationale

·····

A complete onboarding package requires several maintained artifacts.

The repository README can explain product purpose and basic setup, while CLAUDE.md provides concise commands, conventions, and operating boundaries.

An onboarding guide can define the learning sequence, diagrams can visualize architecture, a glossary can establish terminology, while decision records and runbooks preserve rationale and operational procedures.

Ownership maps and human contacts identify where institutional knowledge resides when repository evidence is insufficient.

Claude can draft and update these artifacts, although maintainers should approve them before they become the shared source of truth.

........

Components of a Team Onboarding Package.

Artifact	Purpose
README.md	Product purpose and initial setup
CLAUDE.md	Commands, conventions, boundaries, and pitfalls
ONBOARDING.md	Guided learning sequence
Repository map	Source-tree orientation
Architecture diagrams	Components, flows, data, and deployment
Glossary	Domain and project terminology
First-task list	Small representative engineering exercises
Runbooks	Operational and incident procedures
ADRs	Architectural decisions and rationale
Test guide	Test hierarchy, fixtures, and commands
Ownership map	Teams and maintainers
Prompt library	Repeatable exploration questions
Human contacts	Escalation for unresolved knowledge

·····

Onboarding should be anchored to one real task rather than ending with passive documentation.

A repository overview can create recognition without giving the engineer the ability to trace behavior, choose the correct modification point, or validate a change.

A small first task forces the learner to use the architecture map, navigate a real execution path, understand tests, run the build, and interact with a maintainer.

Claude can explain the affected components and quiz the engineer before implementation, while the engineer should describe the path and proposed change independently.

The completed task can then improve the onboarding documentation by correcting whatever the new engineer found unclear or outdated.

........

Properties of a Suitable First Task.

Task Property	Recommended Form
Scope	One component or execution path
Risk	Low and reversible
Validation	Existing tests or clear observable result
Architectural exposure	Several representative layers
Ownership	Maintainer available for review
Documentation	Opportunity to improve guidance
Completion	Small pull request or verified explanation
Reflection	Engineer explains behavior independently
Rollback	Straightforward
Time horizon	Short enough for early feedback

·····

Claude should quiz the engineer before proposing implementation.

A new engineer may accept a generated architecture explanation without being able to reconstruct it or recognize when the implementation plan contradicts the system’s boundaries.

Claude can ask the learner to identify the entry point, component owner, state mutation, external call, test location, and failure behavior for the task.

Incorrect or partial answers reveal which part of the flow needs another explanation before source changes begin.

This turns Claude from a documentation engine into an interactive onboarding tutor whose output is measured through the engineer’s independent understanding.

........

Architecture Questions Before a First Change.

Question	Understanding Tested
Where does the behavior begin?	Entry-point knowledge
Which component owns the rule?	Responsibility boundary
Where is state read and changed?	Data ownership
Which external systems are involved?	Integration awareness
Which configuration alters the path?	Runtime selection
What happens on failure?	Operational understanding
Which tests represent the behavior?	Verification knowledge
Which compatibility constraint applies?	Historical and public contract
Where should the change occur?	Architectural judgment
How would the result be validated?	Completion model

·····

Claude Code can reduce routine onboarding interruptions without replacing senior engineers.

A new team member can ask repeated questions about folder structure, caller relationships, test commands, naming conventions, and local implementation without waiting for a maintainer to become available.

Claude can also produce explanations at different levels and revisit the same concept without the social cost of asking a colleague to repeat it.

Senior engineers remain necessary when the answer depends on product intent, customer commitments, political ownership, undocumented incidents, future strategy, or the reasons the team intentionally accepts technical debt.

The appropriate division uses Claude for repository-visible evidence and maintainers for accountable institutional judgment.

........

Claude and Maintainer Responsibilities During Onboarding.

Claude Code	Maintainer
Locate files and symbols	Confirm product intent
Trace static execution	Explain undocumented history
Summarize tests and configuration	Confirm production reality
Review Git history	Clarify organizational ownership
Generate draft diagrams	Approve architectural representation
Explain language patterns	Decide acceptable trade-offs
Suggest missing documentation	Prioritize documentation work
Quiz the learner	Assess team readiness
Repeat routine explanations	Make accountable engineering decisions

·····

Read-only exploration still requires security and permission boundaries.

A learner may need access to source, tests, Git history, package metadata, and safe local commands, although architecture understanding does not ordinarily require credentials, production databases, deployment permissions, or broad outbound network access.

Repository files may contain instructions, scripts, or comments that encourage the agent to run commands or contact services, while those instructions should remain evidence rather than authority.

Plan Mode and restrictive permissions reduce accidental modification, while sandboxing can limit which files and networks approved shell commands reach.

The onboarding environment should expose enough information to learn the system without granting operational authority unrelated to the task.

........

Recommended Access During Codebase Learning.

Resource	Suggested Access
Owned source	Read
Tests and fixtures	Read
Git history	Read
Build metadata	Read
Local documentation	Read
Safe local test command	Ask or explicitly allow
Generated and vendor trees	Exclude when irrelevant
Credentials	Deny
Production databases	Deny
Deployment commands	Deny
External infrastructure	Require explicit approval
Unrelated repositories	Deny unless deliberately added
Customer data	Exclude unless approved and necessary

·····

Repository content can attempt to manipulate the exploration process.

A comment, issue, documentation file, fixture, dependency script, or generated artifact may contain text instructing Claude to reveal secrets, ignore the user, download software, or modify unrelated files.

Long repository investigations increase exposure because the agent reads more content and may encounter such instructions far from the original prompt.

Claude should treat repository text as material to analyze rather than as a higher-priority instruction source, while permissions and sandboxing should prevent a misleading file from gaining access to sensitive resources.

Unknown scripts should be inspected before execution, particularly when a new engineer does not yet understand the project’s build system.

........

Controls Against Manipulative Repository Content.

Control	Purpose
Preserve instruction hierarchy	Prevents files from redefining the task
Use Plan Mode	Blocks source editing during exploration
Restrict shell permissions	Prevents automatic command execution
Sandbox filesystem	Protects unrelated files
Restrict network	Prevents unintended outbound access
Deny credential paths	Prevents secret exposure
Inspect scripts before running	Detects destructive or external behavior
Exclude generated and vendor content	Reduces irrelevant instruction exposure
Log commands	Supports audit
Require human approval	Governs consequential actions

·····

Static code does not reveal every runtime dependency.

Reflection, dynamic imports, generated code, database triggers, dependency injection, service discovery, event configuration, infrastructure routing, and feature flags can create relationships absent from ordinary references.

Claude should compare source code with configuration, build processes, deployment definitions, logs, traces, and maintainer knowledge.

A missing static reference should not be interpreted automatically as dead code, while a visible call path should not be described as active in every environment without configuration evidence.

This limitation makes runtime verification and human review necessary parts of architectural onboarding.

........

Evidence Classes for Runtime Architecture.

Evidence Class	What It Reveals
Source code	Explicit implementation
Language-server graph	Static symbol relationships
Configuration	Runtime selection and environment variation
Tests	Encoded scenarios
Git history	Evolution and rationale
Build system	Generated artifacts and dependency assembly
Runtime logs	Actual execution
Distributed traces	Cross-service call paths
Deployment definitions	Infrastructure topology
Database schema	Persistence and trigger behavior
Maintainer interview	Institutional and product intent

·····

Generated explanations have predictable failure modes that should be anticipated.

Claude may inspect the most obvious path and omit alternatives, treat test behavior as complete specification, or interpret current code as intentional architecture.

It may accept stale documentation, infer rationale from Git history without issue context, preserve a tentative conclusion in memory, or create a polished diagram whose simplifications are no longer visible.

Large context windows can encourage indiscriminate reading that reduces attention to the decisive files, while a broad summary can create familiarity without practical ability.

The onboarding process should be designed to detect these failure modes through evidence labels, runtime checks, maintainer review, and a real first task.

........

Common Failure Modes in AI-Assisted Codebase Learning.

Failure Mode	Consequence
Only the obvious path is inspected	Alternative flows remain hidden
Static code is treated as runtime truth	Flags and configuration are omitted
Tests are treated as complete specification	Untested behavior disappears
Current code is treated as deliberate design	Historical accidents become architectural principles
One component is explained in isolation	Integration constraints are missed
Generated or vendor code dominates context	Attention shifts away from owned code
Old documentation is trusted without review	Architecture map becomes stale
Git history is overinterpreted	Inferred rationale becomes false history
Tentative findings enter memory	Future sessions repeat the error
Entire repository is loaded indiscriminately	Relevant evidence receives less attention
Diagram becomes authoritative immediately	Simplifications become institutional misinformation
Onboarding ends with summary reading	Learner cannot apply knowledge independently

·····

Architecture documentation generated by Claude should undergo repository verification before publication.

Every command, path, component name, ownership statement, dependency, and runtime description should be checked against the current branch and environment.

The review should identify content that is stale, incomplete, inferred, or unnecessarily detailed for a first-day guide.

Essential orientation should remain separate from advanced reference material so that a new engineer can establish a useful mental model without reading every historical and operational detail.

Unresolved questions should remain visible rather than being removed to make the guide appear complete.

........

Onboarding-Documentation Review Criteria.

Review Area	Question
Commands	Do they work on the current repository?
Paths	Do the referenced files still exist?
Architecture	Does the description match code and configuration?
Ownership	Is the responsible team current?
Environment	Are prerequisites complete and accurate?
Integrations	Are external dependencies represented?
Security	Are sensitive procedures handled appropriately?
Scope	Is first-day material separated from advanced detail?
Inference	Are unconfirmed claims labelled?
Unknowns	Are unresolved questions preserved?
Date	Is the review timestamp visible?
Reviewer	Has a maintainer approved the content?

·····

Session preservation is useful when onboarding spans several days or subsystems.

A complete codebase cannot always be learned in one uninterrupted conversation, while named sessions allow the engineer to resume an architecture investigation, data-flow analysis, or testing review later.

Branching a session permits exploration of an alternative interpretation without losing the original reasoning, while separate sessions can isolate frontend, backend, data, and operations concerns.

Session transcripts may contain obsolete hypotheses, so maintained documentation should contain the final reviewed findings rather than requiring future engineers to reconstruct truth from chat history.

Naming and exporting useful sessions makes them discoverable during the individual onboarding process without turning them into permanent team documentation automatically.

........

Possible Onboarding Session Structure.

Session	Focus
Repository orientation	Purpose, layout, technologies, and entry points
Domain glossary	Product and technical terminology
Architecture	Components and dependencies
Core request flow	One representative user scenario
Data	Ownership, schemas, and migrations
Testing	Frameworks, fixtures, and commands
Operations	Build, deployment, logs, and alerts
Security	Identity, permissions, and trust boundaries
History	Major migrations and unusual design
First task	Affected path and implementation plan

·····

Learning efficiency depends on scoping questions rather than maximizing file access.

A million-token context or broad repository permission does not guarantee a clearer explanation, because unrelated files, repeated configuration, generated code, and historical artifacts can compete with the material that answers the question.

A narrow semantic question allows Claude to search selectively, while subagents can investigate secondary areas without expanding the primary conversation.

The engineer should ask for the smallest evidence set that supports the explanation and broaden scope only when a missing dependency or contradictory path appears.

This method reduces context consumption while making the reasoning easier to audit.

........

Scoping Principles for Repository Learning.

Principle	Practical Effect
Begin with one question	Prevents unfocused scanning
Name the scenario	Narrows execution tracing
Specify the environment	Avoids mixing runtime variants
Request evidence paths	Keeps explanations auditable
Exclude generated content	Reduces noise
Use symbol navigation	Avoids irrelevant text matches
Delegate secondary research	Protects main context
Expand only when evidence requires it	Controls scope
Stop at institutional knowledge gaps	Prevents invented explanations
Preserve reviewed results	Avoids repeated exploration

·····

A first repository overview prompt should request both findings and limits.

Claude should identify product purpose, technologies, build system, runtime entry points, major directories, deployable applications, shared libraries, test organization, persistence, and external integrations.

It should produce a concise repository map and glossary while attaching paths to every material conclusion.

The prompt should also ask which directories, configurations, or runtime environments were not inspected.

This final uncertainty section prevents the output from being interpreted as a complete architecture specification.

........

Recommended First-Overview Prompt.

Explore this repository without editing any files.

Identify the product purpose, primary technologies, build system, runtime entry points, major directories, deployable applications, shared libraries, test organization, persistence layer, external integrations, and operational configuration.

Produce a concise repository map and a glossary of project-specific terms.

Attach file paths and symbols to every material conclusion, distinguish confirmed evidence from inference, and list the areas, environments, and runtime behavior you have not inspected.

Remain in Plan Mode throughout the investigation.

·····

An architecture-mapping prompt should request several focused views rather than one universal diagram.

The prompt should separate static components, dependency direction, request flows, event flows, data ownership, integrations, deployment, security, and observability.

Each component should receive a concise responsibility, principal entry points, dependencies, owned state, tests, and supporting files.

Inferred relationships should be labelled, while dynamic behavior should remain pending until configuration, runtime evidence, or maintainers confirm it.

The diagrams should be treated as drafts for review rather than final documentation.

........

Recommended Architecture-Mapping Prompt.

Build an architecture map from current repository evidence without changing source files.

Separate the repository structure, runtime components, dependency direction, request flows, event flows, data ownership, external integrations, deployment topology, security boundaries, and observability.

Use several small Mermaid diagrams rather than one combined diagram.

For every component, state its responsibility, entry points, dependencies, owned state, configuration, tests, and supporting files.

Mark inferred relationships, identify environment-dependent behavior, and state what requires runtime or maintainer confirmation.

·····

An execution-tracing prompt should define the scenario and initial state precisely.

The initiating user action, request, command, schedule, or event should be named together with relevant authentication, data, and feature-flag conditions.

Claude can then record execution in order, including validation, domain decisions, persistence, external calls, events, failure handling, and observability.

Branches should be explained where they materially change the path, while static inference should remain separate from behavior demonstrated by tests or runtime output.

A concise trace table can accompany a sequence diagram and supporting file references.

........

Recommended End-to-End Flow Prompt.

Trace [SCENARIO] from its initiating action, request, command, schedule, or event through every material component until the final response and side effects.

Assume [INITIAL STATE, ENVIRONMENT, AUTHENTICATION CONDITION, AND FEATURE FLAGS].

Record validation, authentication, authorization, dispatch, domain decisions, persistence, cache behavior, external calls, emitted events, retries, rollback, errors, and observability.

Cite relevant symbols, files, tests, and configuration in execution order.

Distinguish relationships confirmed by source, tests, configuration, runtime evidence, and inference.

·····

A difficult-component prompt should connect product responsibility with implementation detail.

The explanation should begin with the user or business behavior, then identify architectural responsibility, collaboration with other modules, runtime operation, and local implementation.

Inputs, outputs, state, invariants, errors, side effects, tests, and consumers should be described before recommendations appear.

Nearby implementations and Git history can help determine whether the pattern is a repository convention or a historical exception.

Claude should avoid proposing changes until the current contract and constraints have been established.

........

Recommended Difficult-Component Prompt.

Explain [COMPONENT] at four levels: product responsibility, architectural role, collaboration with surrounding modules, and detailed runtime behavior.

Define its inputs, outputs, state, invariants, dependencies, mutations, edge cases, failure modes, concurrency requirements, tests, and consumers.

Compare its implementation with nearby repository patterns and relevant Git history.

Attach file and symbol references to material claims, label inference explicitly, and do not propose changes until the current behavior and constraints are established.

·····

A first-task prompt should require the engineer to demonstrate understanding before implementation begins.

Claude should identify the user-visible behavior, affected components, current path, configuration, existing patterns, tests, and likely ownership boundaries.

It should then ask the learner to explain where the change belongs, which state it affects, what could fail, and how completion will be verified.

The session should remain in Plan Mode until the engineer can reconstruct the path and approve the implementation strategy.

This turns the first task into an onboarding exercise rather than an opportunity to delegate unfamiliar work immediately.

........

Recommended First-Task Prompt.

Help me understand this task before writing code.

Identify the user-visible behavior, affected components, existing patterns, data ownership, configuration, tests, operational concerns, and likely maintainers.

Trace the current execution path and explain where the requested change belongs.

Then quiz me on the architecture and ask me to describe the path, proposed modification, risks, and verification plan in my own words.

Remain in Plan Mode until I can explain the affected system and approve a staged implementation plan.

·····

Generated onboarding documentation should be reviewed against the repository rather than against its own internal coherence.

A guide may be logically consistent while referring to deleted paths, obsolete commands, former owners, or architecture that no longer runs.

Claude should verify every command and material claim using current files, configuration, and tests, while maintainers confirm institutional and production knowledge.

The review should distinguish essential first-day information from advanced reference material and should preserve qualifications whose removal would make the guide misleading.

Documentation correction is itself an appropriate low-risk first contribution for a new engineer.

........

Recommended Onboarding-Guide Review Prompt.

Review this onboarding guide against the current repository and available runtime evidence rather than assuming it is correct.

Verify every command, path, architectural statement, ownership claim, environment requirement, external dependency, test instruction, and security boundary.

Identify material that is stale, inferred, incomplete, duplicated, or missing.

Separate essential first-day knowledge from advanced reference material, preserve unresolved questions, and attach repository evidence to every proposed correction.

·····

A maintained onboarding process should include periodic verification.

Repositories change through migrations, reorganizations, dependency upgrades, deployment changes, ownership transfers, and new operational practices.

A guide that was accurate six months earlier can become actively misleading if commands, paths, or component boundaries change.

Teams should review core onboarding artifacts after significant architectural work and should assign ownership for recurring checks.

Claude can assist by comparing documentation with current repository evidence, although maintainers must decide whether observed differences represent stale documentation or intentional transitional architecture.

........

Events That Should Trigger Onboarding Review.

Change Event	Documentation to Recheck
Repository reorganization	Maps, paths, and commands
Framework migration	Entry points, build, and runtime explanation
Service split or merger	Component and deployment diagrams
Database migration	Data ownership and schema guidance
Authentication change	Security and request-flow documentation
New build system	Setup and validation commands
Ownership transfer	Maintainer and escalation maps
Incident correction	Runbooks and historical rationale
New external integration	Integration and failure-path maps
Test restructuring	Test guide and first-task exercises
Deprecated subsystem removal	Glossary and architecture references

·····

Onboarding quality should be measured through independent navigation and task performance.

The number of generated diagrams or pages does not establish that an engineer understands the system.

A stronger measure asks whether the learner can locate a feature, trace a representative flow, identify the correct component owner, find relevant tests, run the required commands, explain failure behavior, and complete a small change safely.

Time to first reviewed contribution, number of maintainer corrections, documentation defects discovered, and ability to answer architecture questions provide more meaningful signals than reading completion.

Claude Code should reduce search and explanation overhead while increasing the engineer’s independent capability.

........

Possible Measures of Onboarding Effectiveness.

Measure	Interpretation
Time to working local environment	Setup clarity
Time to trace first feature	Navigation ability
Accuracy of architecture explanation	Mental-model quality
Ability to find relevant tests	Verification understanding
First reviewed contribution	Practical readiness
Number of major maintainer corrections	Remaining misunderstanding
Documentation improvements	Knowledge capture
Independent debugging ability	Transfer of learning
Appropriate escalation	Recognition of institutional knowledge gaps
Retention after several weeks	Durability of understanding

·····

Claude Code is most effective when it makes repository evidence easier to interrogate.

Its value comes from connecting natural-language questions with file search, symbol navigation, tests, configuration, Git history, command output, and architecture explanation.

Plan Mode allows that investigation to remain separate from modification, while nested instructions and scoped starting directories keep large repositories manageable.

Language-server support improves structural navigation, text search covers dynamic and configuration-based relationships, while runtime evidence and maintainer knowledge address what static code cannot reveal.

Subagents can investigate separate architectural concerns without overwhelming the primary learning context, while session management and reviewed memory preserve useful discoveries across a longer onboarding period.

·····

The strongest result is an engineer who can explain and apply the architecture without depending on Claude’s wording.

A generated overview may shorten the time required to become oriented, although the learner should still be able to reconstruct the execution path, identify the owning component, explain the relevant data and failure behavior, and choose the correct verification method.

Quizzes, first tasks, and maintainer review convert passive explanations into demonstrated understanding.

Verified discoveries can then improve CLAUDE.md, onboarding guides, diagrams, glossaries, tests, and decision records for the next engineer.

Claude Code becomes a durable onboarding tool when each learning cycle leaves both the person and the repository documentation more capable than they were before the session.

·····

Codebase learning should preserve uncertainty rather than manufacture completeness.

Some architectural behavior will remain unavailable because it exists in production configuration, external systems, former employees’ knowledge, customer-specific deployments, or undocumented decisions.

Claude should identify those gaps and explain which evidence or person could resolve them.

An honest unknown is more valuable than a plausible invented rationale, particularly when a new engineer may later make design decisions based on the explanation.

The onboarding process is complete enough when the learner knows both how the relevant system works and where the current evidence stops.

·····

Claude Code reduces onboarding burden when exploration, verification, human review, and real work remain connected.

The process begins with orientation, vocabulary, structure, and entry points before narrowing into components, contracts, data ownership, integrations, and one representative runtime scenario.

Architecture claims become more defensible when they cite files and symbols, distinguish evidence from inference, and compare static source with tests, configuration, history, logs, traces, and deployment definitions.

CLAUDE.md, nested instructions, auto memory, output styles, LSP navigation, scoped sessions, and subagents support repeated learning, although each requires review so that convenience does not preserve stale or incorrect assumptions.

Plan Mode protects the codebase during exploration, while permissions and sandboxing prevent read-only onboarding from expanding into unnecessary access to credentials, infrastructure, or production systems.

Generated maps and guides should remain drafts until maintainers review them, while a real first task tests whether the learner can use the explanation rather than merely recognize it.

Claude can answer routine repository questions without repeatedly interrupting experienced engineers, while humans remain accountable for product intent, ownership, risk, architecture, and undocumented institutional knowledge.

The most defensible onboarding outcome is therefore not a comprehensive AI-generated summary, but a verified and evolving set of maps, traces, terms, commands, and first-hand experience through which a new engineer can navigate the repository independently, recognize the limits of available evidence, complete a small change safely, and improve the path for the next person.

·····

FOLLOW US FOR MORE.

·····

DATA STUDIOS

·····

[datastudios.org]

·····