;
};
export const LearnerPrimer = ({items = [], lang = "zh"}) => {
const t = lang === "en" ? {
title: "Before this unit, be honest with yourself",
sub: "If you can't answer these, that gap is exactly what this unit closes."
} : {
title: "讀這個單元前，先誠實面對",
sub: "這幾題答不出來，正是這個單元要替你補的洞。"
};
const css = `
.lp-root{--lp-bg:#FAF7F1;--lp-surface:rgba(191,117,81,0.05);--lp-border:rgba(0,0,0,0.09);--lp-edge:rgba(191,117,81,0.42);--lp-text:#2b2722;--lp-dim:#6f6a62;--lp-accent:#bf7551;border:1px solid var(--lp-border);border-left:3px solid var(--lp-edge);border-radius:13px;background:var(--lp-bg);color:var(--lp-text);overflow:hidden;margin:1.25rem 0;}
.dark .lp-root{--lp-bg:#1b1a18;--lp-surface:rgba(207,138,104,0.07);--lp-border:rgba(255,255,255,0.08);--lp-edge:rgba(207,138,104,0.5);--lp-text:#e7e3da;--lp-dim:#a8a299;--lp-accent:#cf8a68;}
.lp-head{display:flex;align-items:center;gap:9px;padding:13px 18px 11px;border-bottom:1px solid var(--lp-border);background:var(--lp-surface);}
.lp-ic{color:var(--lp-accent);flex-shrink:0;}
.lp-htx{display:flex;flex-direction:column;gap:1px;min-width:0;}
.lp-title{font-size:14px;font-weight:650;line-height:1.3;letter-spacing:.01em;}
.lp-sub{font-size:12px;color:var(--lp-dim);line-height:1.4;}
.lp-list{list-style:none;margin:0;padding:10px 18px 14px;display:flex;flex-direction:column;gap:0;}
.lp-item{display:flex;align-items:baseline;gap:11px;padding:7px 0;font-size:14px;line-height:1.6;border-top:1px solid var(--lp-border);}
.lp-item:first-child{border-top:none;}
.lp-mark{flex-shrink:0;color:var(--lp-accent);font-size:13px;font-weight:700;line-height:1.55;font-variant-numeric:tabular-nums;opacity:.85;}
.lp-q{flex:1 1 0;min-width:0;color:var(--lp-text);}
@media (max-width:620px){.lp-head{padding:12px 14px 10px;}.lp-list{padding:8px 14px 12px;}}
`;
return
{t.title}{t.sub}
{items.map((q, i) =>
{String(i + 1).padStart(2, "0")}{q}
)}
;
};
**What this unit solves**
Before learning any tool's configuration details, build a universal coordinate system first. Grasp the two axes -- scope and setting type -- and you can immediately judge where any configuration file belongs, whether it will be overridden by something else, and whether it should be committed to version control.
## Learning objectives
* [ ] Use the scope axis (managed, user, project, local) to describe the effective range of any setting.
* [ ] Use the setting-type axis (personalization, memory, rules, privacy, permissions, automation) to classify any configuration item.
* [ ] Explain the override precedence order and distinguish the three distinct layer semantics: override, concatenate, and merge.
* [ ] Correctly identify which configuration files should be committed (team-shared) and which should be gitignored (personal).
***
## 1. First axis: scope
The same setting can appear at different scopes; which one takes effect depends on precedence. Using Claude Code as the primary reference, five layers from highest to lowest (as of 2026-05 official documentation \[1]):
**One rule to remember**
"The closer a setting is to the current task, the higher its precedence." Managed policy is the only exception that flows top-down and cannot be overridden -- that is for IT administration. The remaining four layers all obey "closer wins."
### Three layer semantics: override vs concatenate vs merge
This is the biggest misconception people have about "layers": **not all settings use "higher layer overrides lower layer."** Claude Code has at least three distinct merge behaviors. Mixing up these mental models costs a great deal of debug time (\[1]\[2]):
| Semantic | Applies to | Behavior |
| --------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Override** | The same key in `settings.json` | The higher-priority layer's value replaces the lower layer's; only one value takes effect |
| **Concatenate** | `CLAUDE.md` / memory rule files | All layers are **loaded in full** without overriding each other; spliced into context in root-to-current-directory order |
| **Merge** | `permissions` allow / ask / deny rules | Rule arrays are **concatenated and deduplicated** across layers into one set; evaluated in `deny, ask, allow` order; the first matching rule wins; **`deny` cannot be unlocked by any layer's `allow`** |
In other words: your `~/.claude/CLAUDE.md` and the project's `./CLAUDE.md` **do not override each other** -- both are read (user layer first, project layer second). But for the same key in `~/.claude/settings.json` and `.claude/settings.json`, the higher-priority layer wins. Treating these two situations as identical is the root cause of confusion like "I clearly set this at the user layer, why does the project behave differently?"
## 2. Second axis: setting type
Scope determines "where it takes effect"; type determines "what it controls." Six types:
* **Personalization**: role, language, tone, output format.
* **Memory**: facts and preferences persisted across sessions (short-term vs long-term covered in [01-4](/en/code-agent/foundations/context-engineering)).
* **Rules / instructions**: project conventions and constraints (`CLAUDE.md`, `AGENTS.md`, `.claude/rules/`).
* **Privacy**: training opt-out, retention period, temporary conversations.
* **Permissions**: which tools can execute, which paths can be read or written (allow / ask / deny).
* **Automation**: skills, hooks, workflows.
Cross the two axes and any configuration item maps to exactly one cell: a rule is "rules type x some scope," a permission is "permissions type x some scope."
## 3. Two axes combined: decision tool
Treat "type x scope" as a matrix. Every time you need to place a setting, pick these two axes first -- the result determines which file it goes in and whether to commit it.
**Three settings, three locations**
1. **Team-shared coding style conventions**: rules type x project scope -- write into `./CLAUDE.md`, **commit to version control**, shared with the team.
2. **Your personal sandbox URL and preferred test data**: personalization / rules type x local scope -- write into `./CLAUDE.local.md`, **add to `.gitignore`**, only you can see it, does not pollute the team.
3. **Your cross-project language preference (always reply in Traditional Chinese)**: personalization type x user scope -- write into `~/.claude/CLAUDE.md`, applied to every project on your machine.
All three are "rules / personalization" type; the only difference is scope, and scope directly determines "commit or gitignore, who can see it." That is the two-axis coordinate system in practice: fix the type, fix the scope, and the file location and version-control strategy fall out automatically.
**When the same key appears at multiple layers, decide first: override or concatenate**
If you set `model` in `~/.claude/settings.json` and also set a different `model` in `.claude/settings.json`, the **project layer wins** (override; closer wins). But if you write style rules in both `~/.claude/CLAUDE.md` and `./CLAUDE.md`, **both take effect** (concatenate). When they conflict, Claude may follow either one, so do not let rules at two layers contradict each other.
## 4. Commit vs gitignore (critical practice)
The most direct version-control consequence of the scope axis is this binary:
* **Commit (version control, team-shared)**: rules and settings the whole team should follow consistently. `./CLAUDE.md`, `.claude/settings.json`, `.claude/rules/`, `AGENTS.md`.
* **gitignore (personal, not shared)**: personal overrides, secrets, local paths. `./CLAUDE.local.md`, `.claude/settings.local.json`, anything containing tokens.
This is the same mental model as `.env` vs `.env.example`: the shareable template goes into version control; the instance that contains secrets stays local. The test is simple: **if a teammate applied this setting, would it help them or leak something about you?** If it helps them, commit it; if it leaks you, gitignore it.
**Secrets never go in a file that will be committed**
The most common and most expensive mistake: writing an API key or token into `.claude/settings.json` (which is committed) instead of `settings.local.json` (gitignored). Once pushed to a remote, it is effectively public. Secrets, local absolute paths, and personal sandbox addresses always go in the local layer.
## 5. Mapping any new tool to this model
The value of this coordinate system is that it works across tools. When you encounter an unfamiliar tool, answer these five questions in order and you understand its configuration surface without reading the entire documentation:
Which file or directory holds personal preferences that apply to all your projects?
Which file is committed to version control and takes effect for the whole team?
Is there a gitignored personal configuration entry point?
How do you opt out of data training or set a data retention period?
Can you restrict what the tool reads, writes, and executes? Where are deny / ask / allow configured?
Answer all five and you can start using it safely, rather than discovering "I set this and it did nothing" or "I accidentally committed a secret" after the fact.
## Tool comparison
Configuration layer mapping across vendors (as of 2026-05; exact filenames and mechanisms are subject to each vendor's current documentation; per-item details in [02-2](/en/code-agent/configuration/anthropic-claude-setup) and [02-6](/en/code-agent/configuration/other-tools-comparison)):
| Scope | Anthropic Claude (primary) | OpenAI Codex | Google Antigravity | GitHub Copilot CLI | Cursor |
| -------------- | ------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| User level | `~/.claude/` (`settings.json`, `CLAUDE.md`) | `~/.codex/config.toml` | `~/.gemini/` (`GEMINI.md`, `AGENTS.md`) | `~/.copilot/copilot-instructions.md` (single file) | User Rules (GUI) |
| Project level | `.claude/`, `./CLAUDE.md` | `AGENTS.md`, `.codex/config.toml` (loaded only when trusted) | `.agent/rules/` (singular), `GEMINI.md` | `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md` | `.cursor/rules/*.mdc` |
| Local override | `settings.local.json`, `CLAUDE.local.md` | CLI flags | (No explicit dedicated local layer; workspace is the effective unit) | `~/.copilot/copilot-instructions.md` (CLI supports a local layer, used alongside `AGENTS.md`) | (No equivalent dedicated local layer; see 02-6) |
**The comparison table gives coordinates, not details**
This table tells you "what the same layer is called in your tool." The exact semantics of each cell (what overrides what, which files are committed) are fast-moving facts; verify them in 02-2 (Claude) and 02-6 (others) with dated notes. The key takeaway: almost every vendor has the user / project / local scope axis; the differences are only in filenames and how complete the local layer is.
## Common pitfalls
**Anti-pattern list**
* **Assuming all layers use "higher overrides lower"**: `settings.json` uses override, but `CLAUDE.md` uses concatenation and `permissions` uses merge. Using the wrong mental model has a real debug cost (Section 1).
* **Writing personal preferences into team-shared project rule files**: your language preference and sandbox URL in `./CLAUDE.md` pollute every teammate's context. That belongs in `CLAUDE.local.md` or the user layer.
* **Writing secrets into committed configuration files**: `settings.json` goes into version control; secrets belong in `settings.local.json` (Section 4).
* **Not knowing a setting is being overridden by a higher-priority layer**: "I clearly set this, why isn't it working?" is almost always a closer layer covering it, or a managed policy locking it out. First confirm which layer is actually in effect.
## Self-check
**The bar for passing this unit**
1. Can you name where your primary tool's "user-level" and "project-level" configuration files live, and which ones are already committed to version control?
2. Given an API key, a team style rule, and a personal language preference, can you say for each: "which cell, commit or gitignore?"
3. Can you explain why `~/.claude/CLAUDE.md` and `./CLAUDE.md` do not override each other, while the same key in two `settings.json` files does?
## Sources and further reading
Factual claims are grounded in official documentation; fast-changing items are annotated as of 2026-05.
* \[1] Anthropic, "Claude Code settings" (setting precedence: managed, CLI, local, project, user; file locations; permissions as cross-layer merge), Claude Code Docs. [https://code.claude.com/docs/en/settings](https://code.claude.com/docs/en/settings) (as of 2026-05)
* \[2] Anthropic, "How Claude remembers your project" (`CLAUDE.md` hierarchy and concatenation loading, `CLAUDE.local.md`, `@path` import syntax, `.claude/rules/`, Claude Code reads `CLAUDE.md` not `AGENTS.md`), Claude Code Docs. [https://code.claude.com/docs/en/memory](https://code.claude.com/docs/en/memory) (as of 2026-05)
* Related: [02-2](/en/code-agent/configuration/anthropic-claude-setup) Claude configuration item by item; [02-6](/en/code-agent/configuration/other-tools-comparison) configuration comparison across tools; [04-1](/en/code-agent/customization/claude-md-memory) CLAUDE.md and memory files; [04-2](/en/code-agent/customization/rules) rules files.