The animated scenes show on a laptop or desktop screen.

CLAUDE.md

CLAUDE.md and rules: what Claude Code always knows

Razorpay's payments platform team wants Claude Code to follow the team's conventions without every engineer typing them into each chat. This chapter puts those conventions into files that Claude Code reads by itself. The team tries three designs that fail: one engineer's personal file, one shared file that grows to 640 lines, and a testing note copied into thirty folders. The chapter ends with rules that load only for the files they name, and a hook that blocks an edit that logs a full card number.

What this chapter shows you

  1. Claude Code reads CLAUDE.md at the start of every session. Files from three levels are added together, the folder level joins when Claude works in that folder or Claude Code starts there, and none of them overrides another.
  2. A CLAUDE.md in one engineer's home folder never reaches a teammate. A new joiner's refund code stores ₹499 as 499.00 until the conventions move into the project's file.
  3. A 640-line CLAUDE.md loads everything into every session. A CLAUDE.md in a lower folder loads when Claude works in that folder, while @import splits the file into several files and loads the same lines.
  4. Path-scoped rules load only for the files they name. One testing rule replaces thirty copies, and a hook blocks an edit that logs a full card number.
  5. Check yourself. Plan where the payouts team's instructions go, then answer one question in the exam's style.

Part 1: Claude Code reads CLAUDE.md at the start of every session

Razorpay builds the software that lets businesses in India take payments online. Its payments platform team, about 40 engineers in Bengaluru, keeps its code in one called payments-platform. The team uses , Anthropic's coding tool, to write, fix and document that code. Claude Code runs on the engineer's laptop. It sends the work to Claude, and when Claude asks for a command or a file, Claude Code runs the command or opens the file. The team has conventions that every change must follow, such as the command that runs the tests and the way messages begin. The tech lead wants every session to start with these conventions already in Claude's context.

CLAUDE.md is a file of instructions that Claude Code reads before the first prompt.

is a plain file of instructions that Claude Code reads at the start of every and places in Claude's . It holds what a team would otherwise repeat in every chat: the build and test commands, coding conventions, the layout of the repository and rules such as “never log card numbers”.

Razorpay's file sits at the of payments-platform and is 40 lines long. It is committed to with the code, so every engineer who has the repository has the same file.

Each session starts with an empty context. When an engineer types claude in a inside payments-platform, Claude Code finds the file and reads it at launch. It puts the lines in the first , ahead of the engineer's first , and every later request in the session carries them again. It does the same in every new session.

# payments-platform

A heading. Markdown marks headings with #, and Claude reads them as the sections of the file.

Code lives in services/, libs/ and infra/.

The layout of the repository, so Claude knows where to look before it searches.

## Build and test
- Run tests with `pnpm test`.

The command that runs the tests. Without this line, Claude would have to work the command out from the files or ask for it.

## Commits
- Start each commit message with the service
  name, such as "refunds: fix rounding".

A team convention for commit messages. Each instruction is one short line that a reviewer could check.

Claude reads CLAUDE.md as context, the same way it reads a prompt. It usually follows the instructions, and nothing outside Claude checks that it did. So CLAUDE.md is advice that Claude usually follows. A rule that must hold every time also needs a hook, code that Claude Code runs itself before an action, which Part 4 shows.

CLAUDE.md

On Monday an engineer starts Claude Code. The new session's context is empty, so Claude Code first gives Claude the team's CLAUDE.md: the test command, the commit format and where the code lives.

An engineer asks Claude to fix the failing refunds test. Claude knows to run pnpm test because the team's CLAUDE.md says so, and Claude Code runs it. CLAUDE.md is advice, and nothing checks that Claude followed it.

On Tuesday the engineer starts a new session, which also starts with an empty context. Claude Code reads CLAUDE.md again, and Claude gets the same three instructions before the first task.

Every session starts this way. Claude Code loads CLAUDE.md before the engineer's first prompt, Claude follows it as context, and Claude Code does not check the work against it.

Claude Code read CLAUDE.md at the start of each session, when Claude's context was empty, and nothing checked Claude's work against it.

Claude Code sends requests to Claude through Anthropic's API, the service that programs use to reach Claude, and each request carries the context. Chapter 7 builds an agent on the same API. The request starts with Claude Code's own . The CLAUDE.md lines follow it as a , the same part of the request that carries the engineer's own messages, and the engineer's prompt comes after them. Claude reads the lines as context to follow.

CLAUDE.md in every session

The engineer types claude in the terminal inside payments-platform. Claude Code finds CLAUDE.md at the root and reads its 40 lines.

Claude Code builds the API request: its own system prompt first, then the CLAUDE.md lines as a user message, then the prompt “Fix the failing refunds test”.

Claude Code sends the API request to Claude. The CLAUDE.md lines are in Claude's context before Claude reads the prompt.

Claude asks Claude Code to run pnpm test, the test command from CLAUDE.md, with the Bash tool, which runs a terminal command. Claude Code runs it: 211 tests pass and 1 fails, refund.test.ts.

Claude Code sends the result to Claude in a second API request. It carries Claude Code's system prompt, the CLAUDE.md lines and the prompt again, then Claude's tool request and the test result.

The engineer ends the session with /exit and starts a new one. Claude's context empties, and Claude Code puts CLAUDE.md into the new session's first request again.

Claude Code put the same 40 lines into the first request of each session, after its own system prompt and before the engineer's prompt, and the second request, with the test result, carried them again. Claude read them as context.

An older Anthropic article, from 25 November 2025, says CLAUDE.md becomes part of the system prompt, while Claude Code's documentation as of 22 October 2026 says it follows the system prompt as a user message. The difference changes nothing a team does: either way the lines are in Claude's context from the first request, and Claude reads them as guidance.

CLAUDE.md files at three levels are added together, and none overrides another.

Claude Code reads CLAUDE.md files from three levels. The file, ~/.claude/CLAUDE.md, sits in the engineer's and applies to every project on that laptop. The file, CLAUDE.md or .claude/CLAUDE.md at the root of the repository, is committed to git and reaches everyone who has the repository. The third level, which the exam guide calls the , is a folder CLAUDE.md: a CLAUDE.md inside one folder of the repository, such as services/refunds/CLAUDE.md, with conventions for the code in that folder.

Two of these paths contain a folder named .claude. The ~/ at the start of ~/.claude/CLAUDE.md means the engineer's home folder, so that file stays on one laptop. .claude/CLAUDE.md without ~/ sits inside the repository and goes to everyone through git.

The tech lead's laptop has all three: her own 12-line file with four instructions, the project's 40-line file and the refunds team's 40-line file.

Claude Code adds the files together, broadest first: the user file, then the project file, then the folder CLAUDE.md when Claude works on a file in that folder or a folder inside it, such as services/refunds/src/refund.ts. The order is only the order in which Claude reads the files. A later or more specific file does not override an earlier one, so Claude sees every line of every file. When two instructions contradict each other, no rule decides which one wins, and Claude may follow either of them.

A CLAUDE.md can also hold comments, notes for people written between <!-- and -->. Claude Code removes them before Claude reads the file, so they use none of Claude's context.

<!-- ~/.claude/CLAUDE.md: the tech lead's own file -->
- Indent with 4 spaces.
- Explain each change in one line.

Two of the four instructions in the tech lead's user file, her two personal habits. The other two are team conventions. Indenting means the spaces at the start of a line of code.

<!-- CLAUDE.md at the root of payments-platform -->
- Run tests with `pnpm test`.
- Indent with 2 spaces.

Two lines of the project file. Its indent rule contradicts hers.

<!-- services/refunds/CLAUDE.md -->
- Every refund carries a reason code.

A line from the refunds team's folder CLAUDE.md, for the code in services/refunds/.

Such a conflict appears in the code Claude writes. An engineer sees each change as a , the list of lines Claude added or changed, with a + before each added line.

CLAUDE.md levels

Claude Code starts on the tech lead's laptop and first reads her own file, ~/.claude/CLAUDE.md. It holds four instructions, among them two of her habits: indent with 4 spaces, and explain each change in one line.

Next Claude Code adds the project's CLAUDE.md, which says to indent with 2 spaces. Her file stays in Claude's context, and the project file is added after it.

Claude asks to open services/refunds/src/refund.ts. Only then does Claude Code add the refunds folder's CLAUDE.md, after the other two files.

Claude now has all three files in its context in that order, with every line of each file.

The tech lead's personal file says to indent code with 4 spaces, and the project's file says 2. Claude Code gives Claude both files and neither one wins, so Claude may follow either. The fix is to keep the rule in one file only.

Claude Code put every line of the three files in front of Claude in one order, including two indent rules that cannot both be followed.

CLAUDE.md levels: user, project and folder

Claude Code starts on the tech lead's laptop and reads ~/.claude/CLAUDE.md first. It is her user file, and it exists only on this laptop.

Next it adds the project's CLAUDE.md under the first file. This file is in git, so every engineer has it.

Claude reads services/refunds/src/refund.ts, and Claude Code adds services/refunds/CLAUDE.md last. Nothing already in Claude's context is removed.

Both indent rules are now in Claude's context. In one session Claude indents with 4 spaces, and in another session with 2.

Claude Code added the three files one after another, and the folder CLAUDE.md did not replace the project file. Neither of two contradicting instructions wins, so the fix is to delete one of them.

As of 22 October 2026, Claude Code's documentation lists two more kinds of file. A managed policy file is placed on every laptop by a company's IT team, and holds one engineer's notes for one project and is listed in .gitignore, so git leaves it out. The exam guide tests the user, project and directory levels.

Part 2: A CLAUDE.md in one engineer's home folder never reaches a teammate

The tech lead used Claude Code for months before the rest of the team did. Over that time she wrote four instructions into her own ~/.claude/CLAUDE.md, in her . Two are her personal habits: indent with 4 spaces, and explain each change in one line. The other two are the team's payment conventions.

Razorpay stores money as a whole number of , so ₹499 is stored as 49900. A decimal value such as 499.00 can have rounding errors. Every call that creates a payment, refund or payout also sends a , so that a retried request is carried out only once.

Attempt one: the payment conventions are in the tech lead's own file.

Her follow both conventions. On Monday a new joiner payments-platform from the , the shared copy on GitHub, and asks Claude Code to add a refund . The same task gives different code on the two laptops.

createRefund({ paymentId, amount: 499.00 })

The new joiner's session. The amount is in rupees with decimals, and the call has no retry key, so a retry could refund the customer twice.

createRefund({ paymentId, amount: 49900,
  retryKey: refundKey(orderId) })

The tech lead's session, for the same task: 49900 paise, and a key built from the order, so a retried call is recognised.

Moving a convention into the shared file takes two steps. An engineer opens a , a proposed change that teammates review and then merge into the remote , and each engineer runs to bring merged changes to their own laptop.

User-level CLAUDE.md

On Monday the new joiner copies payments-platform to his laptop with git clone, and the project's CLAUDE.md comes with the code. The tech lead's ~/.claude/CLAUDE.md is outside the repository, so it stays on her laptop.

Both engineers start Claude Code. On her laptop Claude gets the project file and her own file, which has “Amounts in paise” and “Retry key on every create”. On his laptop Claude gets only the project file.

The new joiner asks Claude to add a refund endpoint. Claude writes the amount as 499.00 and sends no retry key, because neither convention is in his session's context.

The tech lead moves the paise and retry-key lines out of her own file into the project's CLAUDE.md, and the team merges her pull request.

On Tuesday the new joiner runs git pull and gets the updated CLAUDE.md. In his next session Claude stores the amount as 49900 and sends a retry key.

A team convention reaches every engineer only when it is in the project's CLAUDE.md in the shared repository. A file in one engineer's home folder stays on that laptop.

The two payment conventions were on one laptop because they were in one engineer's home folder, which git never copies. Moving them into the project file put them in every clone.

Use /memory to check which CLAUDE.md files are loaded.

is the Claude Code command that lists the files at the user and project levels and opens any of them for editing. When Claude behaves differently on two laptops, /memory is the first way to check which instruction files each session loaded. The list names the place for the user file and the project file even when one of them does not exist yet, and selecting a missing file creates it. The exam guide names /memory as the way to check which files are loaded and to find out why Claude behaves differently on two laptops or in two sessions, so /memory is the answer to give on the exam.

As of 22 October 2026, Claude Code's documentation gives a second command a part in this check. /memory lists the files and opens them for editing, and /context shows under “Memory files” the CLAUDE.md files that actually loaded at launch. On a laptop with a current version of Claude Code, an engineer can run both.

User-level CLAUDE.md is not in git

On the tech lead's laptop, ~/.claude/CLAUDE.md sits outside the folder that git copies. On the new joiner's laptop, Claude writes amount: 499.00 and calls createRefund with no retry key.

Both engineers run /memory. The tech lead's list shows her user file and the project file. The new joiner's list names the place for a user file, and that file does not exist on his laptop.

The team merges a pull request that moves the two payment conventions into CLAUDE.md. The tech lead deletes them from her own file, with her 4-space indent line, and keeps “Explain each change in one line”.

The new joiner runs git pull, and his project CLAUDE.md grows to 42 lines. In a new session Claude writes amount: 49900 with a retry key.

git clone copied what was in the repository, and the tech lead's user file was never in it. After the two lines were merged into the project file, a git pull brought them to the new laptop.

Team conventions go in the project file, and personal habits stay in the user file.

The reverse mistake is to commit a personal habit to the project file. If the tech lead moved “Explain each change in one line” into CLAUDE.md, it would apply to all 40 engineers. That habit stays in ~/.claude/CLAUDE.md, or could go in if it applied to this one project only. She deleted her indent line, because it contradicted the project's rule of 2 spaces, which every engineer follows. The two payment conventions belong to the whole team, so they go in the project file.

The committed CLAUDE.md is also what Claude Code reads when it runs in Razorpay's , which chapter 6 covers.

Part 3: A 640-line CLAUDE.md loads everything into every session

After attempt one, the team treats the root as the place for every convention. Each team adds its own section: checkout, transfers, the API, testing, database and . Within two months the file is 640 lines long.

Attempt two: every team adds its conventions to one shared file.

The drawings in this part count two numbers. Lines at launch are the instruction lines Claude Code loads before the engineer's first prompt. Instruction lines in context are all the CLAUDE.md and rule lines Claude has at a given moment: the lines at launch plus any file Claude Code loads later in the session. Razorpay counts both on the new joiner's laptop, which has no user file, so the counts cover only the project's files. Anthropic gives its size guidance for these files in lines, and every line takes up some of Claude's context. Every line loaded at launch is sent to Claude as in every of the . Claude Code loads the whole root file at launch, so all 640 lines go into every session of every engineer, whatever the task. Anthropic's documentation recommends keeping each CLAUDE.md under about 200 lines, because a longer file uses more of Claude's and Claude follows it less reliably.

One large CLAUDE.md

The root CLAUDE.md is 42 lines, and Claude Code loads all of them at launch. Over two months the checkout, transfers, Terraform and testing teams each add a section to it.

The next morning an engineer starts Claude Code, and it loads the whole file, 640 lines, before the first prompt. The paise rule is at line 412.

The engineer asks Claude to fix rounding in refunds. The paise rule is in Claude's context, but Claude misses it among 640 lines and writes the amount as 499.00.

A longer CLAUDE.md takes more of Claude's context before any work starts, and Claude follows it less reliably.

All 640 lines were in Claude's context from the first prompt, and the one line Claude needed for this task was missed among them.

A 640-line CLAUDE.md in every session

The root CLAUDE.md now has eight sections, from “Build and test” to “Terraform”, and is 640 lines long. Claude Code loads all 640 at launch.

Each of the 40 engineers starts a session, and each session loads the same 640 lines. One engineer is only editing documentation, and Claude Code still loads all 640 lines into that session.

In a refunds change, Claude writes amount: 499.00. The rule against it is at line 412: “Store amounts as integer paise”.

In every session of all 40 engineers, Claude Code loaded the same 640 lines, whatever the task, and among those lines Claude missed the paise rule at line 412.

The team then tries three ways of splitting the file: CLAUDE.md files in folders, @import, and rule files in .claude/rules/.

A CLAUDE.md in a lower folder loads when Claude works in that folder.

A is a CLAUDE.md inside one folder of the , such as services/refunds/CLAUDE.md. The checkout and transfers teams move their sections out of the root file into services/checkout/CLAUDE.md and services/transfers/CLAUDE.md, and the root file drops to 410 lines.

At launch, Claude Code loads the CLAUDE.md in the and in each folder that contains it, up to the repository root. A CLAUDE.md in a folder below the launch folder loads later, when Claude opens or changes a file in that folder or any folder inside it. Opening a file means reading it with Claude's , or with a command that prints one file, such as cat. A search that only lists file names, the Glob tool, does not count. If an engineer starts Claude Code inside services/refunds/, that folder's CLAUDE.md and the root file both load at launch.

Folder CLAUDE.md files

The checkout and transfers teams move their sections out of the root CLAUDE.md into a CLAUDE.md in each team's own folder. The refunds folder already has one.

The next morning an engineer starts Claude Code at the repository root. Claude Code loads only the root file, now 410 lines, and none of the three folder files.

When Claude opens refund.ts for a refunds fix, Claude Code also loads the refunds folder's CLAUDE.md. Lines at launch stay at 410, instruction lines in context rise to 450, and the checkout and transfers files stay out.

The next day the engineer starts Claude Code inside services/refunds/. At launch Claude Code loads the refunds file and also the root file, because the repository root contains services/refunds/: 450 lines.

A CLAUDE.md in a folder below the launch folder loads only when Claude works in that folder, so a session that never touches checkout never loads checkout's file.

The checkout and transfers files stayed out of every session that did not touch those folders, and the refunds file loaded at launch only when Claude Code started inside services/refunds/.

When each CLAUDE.md loads

The new joiner starts Claude Code in payments-platform/. Claude Code loads only the root CLAUDE.md at launch, 410 lines.

The prompt is “Fix rounding in refunds”. Claude asks to read services/refunds/src/refund.ts, and Claude Code opens the file.

Claude Code sends the refunds folder's CLAUDE.md with refund.ts, and the checkout and transfers files stay out. Lines at launch stay at 410, and instruction lines in context rise to 450.

In a second session the new joiner starts Claude Code inside services/refunds/. Claude Code loads the refunds file and the root file at launch, 450 lines.

Moving the two service sections into their own folders took 230 lines out of every launch, because a CLAUDE.md in a folder below the launch folder loads only when Claude works in that folder. Once it loads, it takes up context like any other file, but only in sessions that work there.

@import adds one file's contents to another, and both load together.

An is a line in a CLAUDE.md that names another file with @ followed by its path, such as @docs/standards/retry-keys.md. Claude Code reads the named file and puts its contents into context next to the CLAUDE.md that names it.

The tech lead moves the root file's four topic sections into files in docs/claude/ and puts an @ line in place of each section.

<!-- CLAUDE.md at the root of payments-platform -->
## Build and test
- Run tests with `pnpm test`.

The team-wide sections stay in the root file as before.

@docs/claude/api-conventions.md
@docs/claude/testing.md
@docs/claude/migrations.md
@docs/claude/terraform.md

Four imports, one for each topic section. Each section is now in its own file in docs/claude/, and the root file names it with @ and a path counted from the folder of the root CLAUDE.md, which here is the root of the repository.

Before this change the root CLAUDE.md was 410 lines. With its four topic sections replaced by @ lines, the root file itself is now 150 lines. How many lines load at launch?

An imported file loads whenever the file that imports it loads. The root file loads at launch, so its imports load at launch too. A folder CLAUDE.md loads when Claude works in that folder, and its imports load with it.

Razorpay keeps its company-wide standards in docs/standards/: one file each for retry keys, card-data logging and bank matching. Each service's maintainer knows which standards apply to that service and imports only those into the service's folder CLAUDE.md.

A starts from the folder that holds the file with the @ line. Each .. in it moves up one folder. So ../../ in services/checkout/CLAUDE.md goes up to services/ and then up to payments-platform/, the root of the repository.

<!-- services/checkout/CLAUDE.md -->
Checkout creates payments, so every create
call needs a retry key.

The checkout team's own instruction, which explains why its standards apply.

@../../docs/standards/retry-keys.md
@../../docs/standards/card-data-logging.md

Two imports. Each path starts from services/checkout/, climbs two folders and goes down into docs/standards/. The checkout maintainer chose these two because checkout creates payments and handles card numbers.

<!-- services/transfers/CLAUDE.md -->
Transfers moves money to businesses' bank
accounts in daily batches.
@../../docs/standards/bank-matching.md
@../../docs/standards/retry-keys.md

The transfers file imports bank matching and retry keys, and leaves out card-data logging, because the transfers service never sees card numbers.

An import that points outside the folder where Claude Code was started, such as ../../docs/ when Claude Code was started in services/checkout/, needs the engineer's approval the first time. If the engineer declines, that import stays off. An imported file can import further files, up to four levels deep. A path that contains a space needs a backslash before the space, and an @ written inside backticks, the marks markdown uses to show code, stays as text and imports nothing.

@import

The tech lead moves the API, testing, migrations and Terraform sections out of the root CLAUDE.md into four files in docs/claude/, and puts an @ line naming each file in its place. The root file itself is now 150 lines.

The next morning Claude Code loads the root file and every file it names with @. 410 lines load at launch, the same as before.

The checkout and transfers teams each add an @ line to their folder's CLAUDE.md naming the retry-key standard in docs/standards/. Both lines name the same file, and nothing is copied.

During the session Claude opens a checkout file. Claude Code loads services/checkout/CLAUDE.md and the retry-key standard together. Lines at launch stay at 410.

An @ import keeps each standard in one file. The imported file loads whenever the file that names it loads, so imports save no lines at launch.

The @ lines kept each section and each standard in one file, and every imported file still came in with the file that named it, so the launch mark stayed at 410.

@import in folder CLAUDE.md files

services/checkout/CLAUDE.md imports the retry-key and card-data standards, and services/transfers/CLAUDE.md imports bank matching and retry keys.

The path ../../docs/standards/retry-keys.md is read from the checkout folder: up to services/, up to payments-platform/, then down to docs/standards/retry-keys.md.

Claude reads services/checkout/src/create.ts. The checkout file loads, its two imports load with it, and the transfers file stays out.

The imports let each maintainer choose the standards for one service and keep each standard in a single file. An imported file loaded whenever the file that named it loaded, so the lines at launch stayed at 410.

Part 4: Path-scoped rules load only for the files they name

A team can split CLAUDE.md into one file per topic in .claude/rules/.

The folder holds short markdown files called rules, one topic per file, such as testing.md, api-conventions.md and deployment.md. A rule file loads at launch, exactly as does, unless it starts with a paths list, a short header naming the files it applies to.

The tech lead moves the four imported topic files into .claude/rules/ because a rule file can name the files it applies to, and an imported file cannot. Claude Code reads a paths list only in a rule file. An imported file always loads together with the file that imports it, even if a paths list sits at its top. She makes four rule files, api-conventions.md, testing.md, migrations.md, and deployment.md for Terraform, and deletes the four @ lines from the root file, which stays at 150 lines.

The four rules have no paths list yet, so the same 410 lines still load at launch. The split puts each topic in a separate file that its own team can own and review. The exam guide gives .claude/rules/ as the fix for a CLAUDE.md that has grown too large, and the split reduces the lines at launch only once the rules have paths.

As of 22 October 2026, Claude Code's documentation also lets an engineer keep personal rules in ~/.claude/rules/. They apply to every project on one laptop and, like ~/.claude/CLAUDE.md, are not in .

.claude/rules/

The tech lead turns the four imported files into four rule files in .claude/rules/, each with its own owner, and removes the @ lines from the root file.

The next morning Claude Code loads the root file and all four rule files at launch, 410 lines, the same as before.

The testing team updates testing.md without touching the other three files. A rule file without a paths list loads at launch, exactly as CLAUDE.md does.

Each team could now change its own rule file without touching the others, and all four rule files still loaded at launch, because a rule file without a paths list loads at launch, exactly as CLAUDE.md does.

Attempt three: an engineer copies a testing CLAUDE.md into every test folder.

Razorpay's sit next to the code they test, such as refund.ts and refund.test.ts: 140 test files in 30 folders. Every test must use the shared createTestPayment() and must never call the bank's .

The service sections saved lines when they moved into files, so an engineer tries the same for tests. He has not used paths before and copies the method that worked for the service sections. He takes the testing rule out of .claude/rules/ and copies it as a CLAUDE.md into each of the 30 folders that hold tests. Each copy loads only when Claude works in its folder, so the lines at launch fall from 410 to 340: the root file's 150 lines and the API, migrations and deployment rules, with 80, 30 and 80 lines.

Three months later the test helper is renamed to makeTestPayment(), and the rename has to reach all 30 copies.

A CLAUDE.md copied into every test folder

An engineer copies one testing CLAUDE.md into each of the 30 folders that hold tests. It says to use createTestPayment() and never to call the bank's test system.

By April the test helper is renamed makeTestPayment(). The engineer who renames it replaces the copies one by one, updates 27 of them and misses 3, which still say createTestPayment().

Claude opens batch.test.ts in services/transfers/src, and Claude Code loads that folder's copy, which has the old name. Claude uses createTestPayment(), and the test fails because that function no longer exists.

Claude opens convert.ts in libs/money/src, which is not a test file. Claude Code still loads the testing copy in that folder, because a CLAUDE.md applies to every file in its folder.

Each copy had to be changed separately, three were missed, and every copy loaded for all the files in its folder, tests or not.

Three of thirty CLAUDE.md copies miss a rename

Thirty folders each hold a CLAUDE.md next to their test files.

The pull request that renames createTestPayment to makeTestPayment updates 27 of the 30 CLAUDE.md copies. Three copies still name the old helper.

Claude reads libs/money/src/convert.ts. The libs/money/src/CLAUDE.md copy loads with the old helper name in it, although convert.ts is not a test file.

A CLAUDE.md belongs to a folder, so a convention for one kind of file spread across thirty folders needed thirty copies, and three of them were not updated. Each copy also loaded for files in its folder that were not tests.

A rule with paths loads only when Claude opens or changes a matching file.

A is a rule file in .claude/rules/ that starts with a short header listing file patterns. Claude Code keeps the rule out of Claude's until Claude opens or changes a file that matches one of the patterns, and then adds the rule. While the rule stays out, its lines are not sent as tokens in the 's , so the session uses fewer tokens.

Razorpay deletes the thirty copies and puts the testing conventions back into one file, .claude/rules/testing.md, with a pattern that matches every test file. It gives the other three rules patterns as well.

The header sits at the very top of the rule file, between two lines of three dashes, and is called the . It is written in , a plain format of name: value lines. Its one field is paths, a list of . Claude Code matches each pattern against a file's path counted from the folder that holds .claude/, which for Razorpay is the root of the , such as services/refunds/src/refund.test.ts. In a glob, * matches any characters within one folder or file name, and ** matches any number of folders. So **/*.test.ts matches every path that ends in .test.ts, in any folder at any depth, while *.test.ts on its own would match only test files at the root of the repository. Glob is also the name of Claude's file-search tool, which takes the same kind of pattern. When Claude uses that tool, it gets a list of names, and no rule loads.

---
paths:
  - "**/*.test.ts"
---

The frontmatter. paths lists the files this rule is for: every file whose path ends in .test.ts, in any folder. Claude Code removes this header before Claude reads the rule. The exam guide writes the same idea as **/*.test.tsx for files ending in .test.tsx, or **/*.test.* for test files of any type.

# Testing
- Use makeTestPayment() for test payments.
- Never call the bank's test system from a test.

The rule itself. Claude reads it once it opens or changes a test file, and not before.

---
paths: ["services/*/api/**/*"]
---

The header of api-conventions.md. The list is written on one line, inside square brackets, which is the form the exam guide uses and means the same as the list in the testing rule above. * matches any one service's folder, and **/* matches every file below that service's api folder, such as services/checkout/api/routes.ts.

---
paths: ["**/migrations/**/*"]
---

The header of migrations.md: every file inside any folder named migrations, wherever it sits.

---
paths: ["infra/terraform/**/*"]
---

The header of deployment.md: every file under infra/terraform/.

Path-scoped rules

Three rule files are in .claude/rules/, and 340 lines load at launch. Razorpay deletes the thirty copies and puts the testing conventions back into one rule file, testing.md.

Each of the four rule files gets a paths header naming the files it applies to, and stays in .claude/rules/. The testing rule's pattern is **/*.test.ts.

The next morning Claude Code loads only the root CLAUDE.md at launch, 150 lines, and none of the four rules.

For a refunds fix with a test, Claude opens refund.ts, and Claude Code loads the refunds folder's CLAUDE.md as before. The path does not end in .test.ts, so the testing rule does not load.

Claude opens refund.test.ts. Its path, services/refunds/src/refund.test.ts, matches **/*.test.ts, so Claude Code loads the testing rule during the session, and lines at launch stay at 150.

No file in this session matched the deployment rule's pattern, so Claude Code never loaded it. A rule with paths loads only when Claude opens or changes a file that matches it.

The testing rule loaded only after Claude opened a file whose path matched its pattern, and the deployment rule never loaded, so lines at launch stayed at 150.

Path-scoped rules: paths and glob patterns

testing.md starts with paths: and the pattern "**/*.test.ts", which matches 140 test files in 30 folders. 150 lines load at launch.

The new joiner starts Claude Code in payments-platform/ and asks for a fix in refunds with a test. Claude Code loads only the root CLAUDE.md at launch, and none of the four rule files loads.

Claude asks for Glob("**/*.test.ts"), a search for test files by name.

Claude Code returns 140 test file names from 30 folders. testing.md does not load, because listing names opens no file.

Claude asks to read services/refunds/src/refund.test.ts.

Claude Code sends the file with two more: testing.md, whose pattern the path matches, and the refunds folder's CLAUDE.md. Lines at launch stay at 150, and instruction lines in context rise to 260.

Claude edits refund.test.ts with three instruction files in its context: the root CLAUDE.md, testing.md and the refunds folder's CLAUDE.md. The other three rules and the checkout folder's file never loaded.

The testing rule reached Claude with the first test file Claude opened, and the deployment rule never reached it. One rule with a pattern covered the test files in all 30 folders from one file, while the thirty copies had left three folders with the old helper name.

The exam guide says these rules load “when editing matching files”. As of 22 October 2026, Claude Code's documentation says they load when Claude reads, writes or edits a matching file. This chapter's “opens or changes” covers both: opening is reading, and changing is writing or editing.

Write every pattern in quotes. In YAML, an unquoted pattern that starts with * can stop the header from being read, and Claude Code then loads the rule at launch as if it had no paths. paths is also the only field Claude Code reads from a rule's header, so any other field, such as globs: or when:, is ignored without an error.

A folder's CLAUDE.md suits one area, and a rule with paths suits files spread across many folders.

A folder's CLAUDE.md fits a convention that belongs to one area owned by one team, such as the steps that match each day's transfers with the bank's records in services/transfers/. A rule with paths fits a convention for one kind of file that sits in many folders, such as test files or migrations.

Keeping every convention in the root file under a heading for each area, and leaving Claude to work out which heading applies, is the design the exam guide rejects in its sample question on this topic, because it “relies on inference rather than explicit matching, making it unreliable”.

A is also the wrong place for a convention that must always apply, because a skill loads only when someone calls it or when Claude decides it is relevant. Chapter 4 covers skills.

As of 22 October 2026, Claude Code's documentation lets a skill name file patterns in a paths field, and Claude then loads the skill automatically only when it works with files that match them. A skill kept in one folder's .claude/skills/ becomes available to Claude once Claude works on a file in that folder. The exam guide treats skills as loading on request, and chapter 4 covers the difference.

A rule that must never be broken also needs a hook.

A is code that Claude Code runs at a fixed point in the loop, whatever Claude decides; chapter 8 builds hooks step by step. CLAUDE.md and rules are context that Claude usually follows. Razorpay's root CLAUDE.md says “Never log card numbers”, because a log line with a full card number would expose a customer's card, and that rule must hold every time. Razorpay registers a hook for the Edit and Write tools in Claude Code's settings. The hook runs a short script that Razorpay's team writes. Claude Code runs the hook before it applies each of those edits, and the hook blocks any edit that writes a full card number into a log.

Hooks are listed in . Claude Code reads this file itself and runs the hook before the tool runs, whatever Claude decided, so Claude cannot skip it. For a whole command or path that must never be used, such as running terraform apply, the command that applies Terraform's changes to the live servers, from a laptop, the same settings file also has a list.

{
  "hooks": {
    "PreToolUse": [

The hooks that Claude Code runs after Claude asks for a tool and before the tool runs.

      { "matcher": "Edit|Write",

The tools this hook covers: Edit, which changes part of a file, and Write, which writes a whole file.

        "hooks": [{ "type": "command",
          "command": ".claude/hooks/no-card-logs.sh" }] }
    ]
  }
}

The script Claude Code runs before every Edit or Write call. It reads the change Claude asked for. If the change logs a full card number, the script ends with exit code 2, a number that means refuse, and prints the reason. Claude Code then blocks the edit and sends the reason to Claude. Chapter 8 covers the other answers a hook can give.

Hook

Razorpay has registered a PreToolUse hook in Claude Code's settings. Its CLAUDE.md says “Never log card numbers”, and the line is in Claude's context. Claude still asks to edit refund.ts with a line that logs a full card number.

Before Claude Code applies the edit, it runs Razorpay's own check, the PreToolUse hook. The check finds a full card number going into a log, so Claude Code blocks the edit.

The CLAUDE.md line is an instruction that Claude usually follows, and nothing enforces it. Claude Code runs the hook before every Edit or Write call, whatever Claude has decided, and the hook blocks each edit that logs a full card number.

The CLAUDE.md line told Claude not to log card numbers, and the hook in Claude Code blocked the edit that did.

PreToolUse hook

Razorpay's CLAUDE.md says “Never log card numbers”. Razorpay also registers a PreToolUse hook in .claude/settings.json, which Claude Code runs before every Edit or Write call.

Claude asks to add log.info(card.number) to refund.ts, although CLAUDE.md says not to. Claude Code runs the hook before applying the edit, and Razorpay's script finds the full card number and blocks the edit.

Claude Code sends the reason, “denied: card number in log”, back to Claude.

Claude asks again with log.info(card.last4), which logs only the last four digits. The hook finds no full card number and allows the edit, and Claude Code changes refund.ts.

Claude read the CLAUDE.md line as an instruction not to log card numbers, and the hook blocked the one edit that would have logged one.

Part 5: Check yourself

Plan where the payouts team's instructions go.

Razorpay's payouts team, which sends businesses their money, starts using Claude Code in payments-platform and brings its own instructions. The payouts team's SQL files sit in many folders across the repository, and every service's log lines must carry a request ID, an ID that follows one API call through the logs. The team's lead writes a plan for the instructions. Select every step the plan should include, then check.

Select at least one item first.

Exam question: which rule is in Claude's context?

Razorpay's Terraform conventions are in .claude/rules/deployment.md, which begins with the header paths: ["infra/terraform/**/*"]. An engineer starts Claude Code at the root of the repository and asks Claude to rename a function in the checkout service. Which statement is true?

Razorpay appears in this chapter only to explain how Claude Code and Claude work. Razorpay has no connection with these tutorials, and the code, systems, numbers and events in this chapter were written for the lesson. They do not describe how Razorpay works, and Razorpay does not use this code.