{"slug": "claude-md-rules-for-claude-code-that-you-can-check", "title": "CLAUDE.md Rules for Claude Code That You Can Check", "summary": "A developer from BetterToken outlined best practices for writing CLAUDE.md project rules that make Claude Code predictable, emphasizing observable checks, short contracts, and clear boundaries. The guidance covers structuring rules with goals, boundaries, and reproducible commands, avoiding secrets in the file, and resolving conflicts between root and package-specific rules. The post also references BetterToken's API access for Claude Code integration.", "body_md": "A long list of preferences does not make Claude Code predictable. A useful project rule says what the agent may do, what it must avoid, and which command or diff proves the result. Put architecture notes in `docs/`\n\n; keep the project contract short.\n\n```\n# Project rules\n\n## Goal\n- Keep changes limited to the requested feature.\n\n## Before editing\n- Read package.json and the files named in the task.\n- Do not read or print .env files.\n\n## Checks\n- Run `npm test` after code changes.\n- Run `npm run lint` when TypeScript files change.\n- Report each command, its exit code, and every changed file path.\n\n## Scope and conflicts\n- Rules in `packages/payments/CLAUDE.md` apply only under `packages/payments/`.\n- Inside that directory, the local rule wins when it directly conflicts with this root file.\n- Root security and secret-handling rules always apply.\n\n## Forbidden\n- Do not run deploy, publish, or destructive Git commands.\n```\n\nEach line has an observable result. “Write quality code” does not; “run `npm test`\n\nand report its exit code” does.\n\nUse a goal for the requested outcome, a boundary for files or commands that are off limits, a check for a reproducible command, and a style rule only when it affects review. If a command is not present in `package.json`\n\n, do not invent it. Move long explanations and exception lists to documentation with a link from `CLAUDE.md`\n\n.\n\n`CLAUDE.md`\n\nis part of the repository and is read with the project. Never put API keys, CI tokens, real personal data, or copied API responses in it. State the boundary instead:\n\n```\n- Never open, print, or commit `.env`, `*.pem`, or `secrets/`.\n- Use `API_KEY=your_api_key_here` in examples.\n```\n\nPass a real key through an environment or secret store when a test needs one. Do not paste it into a prompt or handoff.\n\nKeep repository-wide rules in the root file and package-specific rules close to the package. When two files disagree, inspect the instructions visible to the target file, remove the duplicate, and keep the narrower rule local. Do not add another paragraph to hide a conflict.\n\nTest one rule with a reversible task:\n\n`git diff --check`\n\nand inspect `git diff --stat`\n\n.`CLAUDE.md`\n\n.For Claude Code API work, use your own key and check the current Base URL and model in [BetterToken’s Claude Code documentation](https://docs.bettertoken.ai/ai-tools/claude-code?utm_source=devto&utm_medium=syndication&utm_campaign=SEO-100&utm_content=claude-md-rules-for-coding-agent). BetterToken provides API access and usage data; it does not turn `CLAUDE.md`\n\ninto a secret store or replace Claude Code settings.\n\n*Originally published on the BetterToken blog.*\n\nBetterToken provides pay-as-you-go access to AI model APIs through\n\nOpenAI-compatible and Anthropic-compatible endpoints — useful if you are wiring\n\nClaude Code, Codex, or your own tooling to a custom base URL.\n\nSee the [docs](https://docs.bettertoken.ai/?utm_source=devto&utm_medium=syndication&utm_campaign=SEO-100&utm_content=claude-md-rules-for-claude-code) to get started.", "url": "https://wpnews.pro/news/claude-md-rules-for-claude-code-that-you-can-check", "canonical_source": "https://dev.to/bettertoken_ai/claudemd-rules-for-claude-code-that-you-can-check-12ka", "published_at": "2026-08-20 14:59:12+00:00", "updated_at": "2026-08-20 15:15:35.048143+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["BetterToken", "Claude Code"], "alternates": {"html": "https://wpnews.pro/news/claude-md-rules-for-claude-code-that-you-can-check", "markdown": "https://wpnews.pro/news/claude-md-rules-for-claude-code-that-you-can-check.md", "text": "https://wpnews.pro/news/claude-md-rules-for-claude-code-that-you-can-check.txt", "jsonld": "https://wpnews.pro/news/claude-md-rules-for-claude-code-that-you-can-check.jsonld"}}