AnthropicClaude Certified Architect – Foundations2026-103.1 Configure CLAUDE.md files with appropriate hierarchy, scoping, and modular organization
Import the standards each package needs
Completed by the knowledge check
Learning objective
Use @import to load package-specific standards without growing monolithic instruction files.
Core idea
Keep a standard in one maintained file, then import it from the CLAUDE.md files whose packages need it. Claude Code’s syntax is @path/to/import: the path identifies the file to expand into context. “@import” in the objective names the mechanism; it is not a keyword you put before a separate filename.
Imports solve duplication and organization. They do not compress the imported text or make it conditional on the task. The package maintainer chooses the relevant standards, and the importing file’s loading scope determines when they become available. A short root file importing every manual still delivers every manual to context.
How it works
Resolve paths from the importing file
Claude Code accepts relative and absolute import paths. A relative path resolves from the file containing the import, not from the directory where you launched Claude Code. For packages/api/CLAUDE.md, reaching repository-root docs/standards/ requires climbing two directory levels.
For an API package that needs API and shared testing conventions, the instruction file can contain:
# API package standards
@../../docs/standards/api-conventions.md
@../../docs/standards/testing.mdFor packages/web/CLAUDE.md, choose the frontend standard and the same testing source:
# Web package standards
@../../docs/standards/frontend-conventions.md
@../../docs/standards/testing.mdThese are example repository paths. The two packages share one testing document rather than maintain two pasted copies. The API file does not import frontend conventions merely because the document exists. The maintainer’s knowledge of the package supplies that selection; Claude Code expands the specified paths.
Moving an instruction file changes the base used by its relative imports. If you move the API file to packages/api/src/CLAUDE.md, the same ../../docs/standards/testing.md now resolves to packages/docs/standards/testing.md. Recalculate from the importing file’s location. Changing the launch directory does not repair a path written relative to the wrong file.
Distinguish an active import from a displayed example
An import can occur inside ordinary prose, not only on a line by itself. Anthropic’s example uses references such as @README and @package.json alongside an explanatory sentence. Parsing skips Markdown inline code spans and fenced code blocks. Writing the literal text `@README` documents an import without loading the README.
This distinction matters when copying examples into an actual instruction file. The fenced examples in this Bite show what to write; a fence around those lines in your CLAUDE.md would make them inert. A normal Markdown link is also not the documented @path expansion mechanism. Use an active path reference when the content must be included rather than relying on Claude to decide to open a mentioned document.
For paths containing spaces, escape each space with a backslash. A reference to a file under a directory named Design Docs is:
@Design\ Docs/api-conventions.mdWithout the backslash, parsing ends the path at the first space. Quoting the path does not solve this: Anthropic documents that a path wrapped in quotes is not imported. Keep the exact parsing rules separate from conventions you might remember from a shell.
Bound nesting and account for approval
Imported files can import other files recursively, with a maximum depth of four hops. A standards file can include a shared glossary or another focused standard, but a deep chain eventually exceeds the supported depth. Prefer direct, reviewable relationships where a package’s required documents are evident in its instruction file.
Project-level imports are external when their resolved paths lie outside the working directory. The first encounter with external imports in a project shows an approval dialog listing the files. Declining keeps those imports disabled, and the dialog does not appear again. A file existing on disk and a syntactically valid import are therefore insufficient evidence that the session received its contents.
Starting in packages/api/ makes a reference up to root-level docs/standards/ external to that working directory. Starting at the repository root changes that approval boundary, while leaving relative path resolution unchanged. These are two separate calculations: resolve from the importing file, then compare the resolved location with the working directory.
In ordinary Claude Code sessions, user-scope files such as ~/.claude/CLAUDE.md load their imports without that dialog. Cowork sessions on your desktop are an exception: imports from user-scope files that resolve outside the session’s working directory are skipped. Do not generalize the normal user-scope behavior to that environment or treat project imports as automatically trusted.
Key distinctions and trade-offs
Import versus copy: An import keeps one source of a convention. A pasted copy creates another text that must be edited independently. Imports make ownership clearer, but the package still loads the referenced content.
File modularity versus context economy: Imported files are expanded alongside the importing instruction file. They help maintain a short entry point; they do not reduce the total guidance loaded. Trim irrelevant standards rather than hiding them behind a short list of imports.
Path resolution versus external approval: The importing file determines relative resolution. The working directory determines whether a project import is external. One can be correct while the other prevents loading.
For always-needed shared conventions, imports give explicit composition. For topic files discovered automatically, see 3.1.3. For conditional file matching, see 3.3.1 rather than attempting to express conditional imports in prose.
Architecture / decision scenario
A code-generation team has API and web packages. Its root CLAUDE.md contains hundreds of lines of duplicated framework and testing standards. Package maintainers identify one shared testing document and separate API and frontend documents under docs/standards/.
They put two active imports in each package’s CLAUDE.md, using ../../ to resolve from the package directory. The root instruction file retains only conventions required across the repository. A root session loads package instructions when it accesses package files, as described in 3.1.1. Each package receives its selected standards without receiving the other package’s framework guidance.
An API maintainer launches inside packages/api/ and declines the external-import dialog. The testing standard then fails to appear despite the valid path. The diagnosis is approval, not an absent document or a need to paste the full manual into the package file. Another maintainer wrapped the imports in backticks; that failure is parsing. A third added a standards chain deeper than four hops; that failure is nesting.
The review checks the resolved paths, active syntax, chain depth, and applicable external-import approval. It also prunes the documents themselves. Moving text into separate files preserves a maintained source, but only selecting and shortening relevant text reduces what a session must read.
Common exam traps
- Writing
@import standards.mdas though@importwere a directive keyword. - Resolving a relative path from the launch directory instead of the importing file.
- Copying a fenced import example into
CLAUDE.mdand expecting expansion. - Quoting a path with spaces instead of escaping the spaces.
- Treating a valid external path as proof that its import was approved.
- Assuming imports reduce token consumption or can nest without a depth limit.
Where the exam guide differs
The exam guide names “@import syntax” for referencing external files. Claude Code’s memory documentation specifies @path/to/import references, expanded at launch alongside the importing CLAUDE.md. Read an exam option that says “use @import” as adding @path references to the relevant standards files. An option that prints @import <file> as literal syntax uses the guide’s label rather than the product’s syntax; do not copy it into an instruction file.
What to remember
Use active @path/to/import references, resolve relative paths from the importing file, and keep nesting within four hops. Choose standards per package rather than importing everything at the root. Code spans and fences suppress imports; external project imports need approval. Modularity eliminates duplicated sources, while pruning and appropriate loading scope control context cost.
Knowledge check
A repository holds three packages with different stacks. Each package’s sessions should follow only the standards relevant to it, and the team does not want to maintain several copies of any standard. Which approach meets both requirements?
CLAUDE.md for all packagesCLAUDE.md file@path imports to each package’s CLAUDE.md@path imports for all of them to the root CLAUDE.mdCLAUDE.md that names it, so a standard is written once and the package maintainer chooses which ones that package receives. Importing everything from the root keeps one copy but delivers every package’s standards to every session, and pasted copies drift apart.packages/api/CLAUDE.md must import the shared testing standard at docs/standards/testing.md in the repository root. Engineers sometimes launch Claude Code at the root and sometimes in packages/api/; any required external-import approval has been granted. Which line imports the file in both cases?
@../../docs/standards/testing.md@docs/standards/testing.md@import ../../docs/standards/testing.md`@../../docs/standards/testing.md`packages/api/ needs two levels up. The syntax is @ followed by the path; “@import” names the mechanism, not a keyword. Import parsing skips code spans, so the backticked form documents the path without loading it.An API maintainer launches Claude Code in packages/api/. The package’s CLAUDE.md holds the plain-text line @../../docs/standards/testing.md, and that file exists and imports nothing else. The testing standard never reaches the session. The maintainer remembers dismissing a dialog the first time they used this project. What is the most likely cause?
docs/standards/docs/ does from packages/api/ . Claude Code asks once; after a refusal those imports stay disabled and the dialog does not return, so a correct path to an existing file is not enough. A relative path may climb with ../ , imports expand at launch rather than on demand, and a quoted path is not imported at all.A team shortens its root CLAUDE.md from 900 lines to 30 by moving the detail into twelve standards files and importing all twelve with @path lines. What happens to the instruction text a session loads at launch?
CLAUDE.md that references them. Imports organise a long file but do not reduce its context cost, so a short entry point that imports everything still delivers everything. Reducing load means pruning the standards or scoping them, not relocating them.References
- Anthropic, How Claude remembers your project
- Anthropic, Best practices for Claude Code
- Anthropic, Claude Certified Architect – Foundations Exam Guide