Claude — Glossary

README.md is for humans landing on the repo — setup, contributors, license. CLAUDE.md is a prompt anchor for Claude Code — it is auto-loaded at session start and sets the rules of engagement. Typical CLAUDE.md sections: project overview, tech stack pinned versions, hard rules (no vendor edits, plugins over preferences, phpcs Magento2, db_schema not raw SQL), test commands, deployment commands, and known gotchas. Treat it as the contract between you and the model: anything not in CLAUDE.md, the model has to guess at. A good Magento CLAUDE.md is 200–400 lines. More than that and the model starts ignoring the bottom half.

MCP = Model Context Protocol. It's an open spec for plugging external tools (databases, APIs, file systems, browsers) into an AI agent in a structured way — like LSP but for AI capabilities instead of editor capabilities. For Magento: a MySQL MCP server lets Claude run safe read-only queries against your dev database; a Magento Admin REST MCP server lets it call products/{sku} without you copy-pasting tokens; a Cloudflare MCP server lets it bust caches after a deploy. You don't need MCP for day-one Magento work, but past day 30 it is the unlock that turns Claude from a code generator into an agent that can read state and verify its own changes.

A slash-command is a shortcut for a prompt template — running /scaffold-feature just expands a Markdown file in .claude/commands/ and feeds it back into the main thread. A sub-agent is a separate Claude session spawned with its own context, often to keep specialised tools and an isolated working memory. Example: a code-reviewer sub-agent loaded with phpcs + PHPStan + the EQP checklist reviews a diff in 30 seconds without polluting the main implementation thread's context window. Defined in .claude/agents/<name>.md. Rule of thumb: slash-commands for prompts you reuse, sub-agents for roles you delegate to.

Magento's DI container is in Magento\Framework\ObjectManager. You never call new Vendor\Module\Foo() in production code — you type-hint the dependency in your constructor and the container auto-wires it, applying any preference, plugin chain, or virtualType from etc/di.xml. This is what lets a third-party module plug your service without changing your code. Two flavours: Constructor Injection (preferred, type-hinted, eager) and Method Injection via ObjectManager::create() (only legal in factories, repositories, and setup scripts). Calling ObjectManager::getInstance() in a controller is the Magento equivalent of a code smell — reviewers will fail the PR.

A Claude Code hook is a shell command run automatically at lifecycle moments — PreToolUse, PostToolUse, UserPromptSubmit, Stop — configured in .claude/settings.json or ~/.claude/settings.json. It is the same shape as a Magento event observer: a side-effect that fires on a named lifecycle moment without changing the caller's logic. Useful Magento examples: a PostToolUse hook that runs bin/magento setup:di:compile after every etc/di.xml edit, or a Stop hook that runs vendor/bin/phpcs on the changed files. Hooks are the bridge from “AI wrote code” to “AI shipped working code”.