chore(agents): Improve CLAUDE.md clarity and conciseness

[yamadashy]

Simplify project guidelines by removing verbose phrasing, reducing redundancy, and removing rarely-used sections.

• Remove "The assistant shall" prefix from all guidelines for conciseness
• Simplify project overview and commit message sections
• Replace inline PR template with file reference
• Remove PR review and release note guidelines
• Remove non-standard inclusion frontmatter field

138 lines → 101 lines (27% reduction) while preserving all essential content.

Checklist

• Run npm run test
• Run npm run lint

---

[cloudflare-workers-and-pages]

Deploying repomix with    Cloudflare Pages

Latest commit:	d5a9c70
Status:	✅  Deploy successful!
Preview URL:	https://59542594.repomix.pages.dev
Branch Preview URL:	https://chore-improve-claude-md.repomix.pages.dev

View logs

[github-actions]

⚡ Performance Benchmark

Latest commit:	d5a9c70 chore(agents): Replace Airbnb Style Guide reference with Biome
Status:	✅ Benchmark complete!
Ubuntu:	1.44s (±0.03s) → 1.46s (±0.03s) · +0.01s (+0.8%)
macOS:	1.10s (±0.35s) → 1.05s (±0.29s) · -0.06s (-5.0%)
Windows:	2.13s (±0.33s) → 2.15s (±0.40s) · +0.02s (+0.7%)

Details

• Packing the repomix repository with node bin/repomix.cjs
• Warmup: 2 runs (discarded), interleaved execution
• Measurement: 20 runs / 30 on macOS (median ± IQR)
• Workflow run

History

23eaffc fix(agents): Add language tag to commit example code block

Ubuntu:	1.52s (±0.04s) → 1.51s (±0.04s) · -0.01s (-0.9%)
macOS:	1.38s (±0.47s) → 1.38s (±0.40s) · +0.00s (+0.1%)
Windows:	1.97s (±0.60s) → 2.23s (±0.63s) · +0.26s (+13.1%)

b657e5c fix(agents): Add JSON to supported output formats in CLAUDE.md

Ubuntu:	1.49s (±0.05s) → 1.49s (±0.03s) · +0.00s (+0.1%)
macOS:	1.01s (±0.19s) → 1.00s (±0.15s) · -0.02s (-1.8%)
Windows:	1.81s (±0.03s) → 1.83s (±0.07s) · +0.02s (+0.9%)

d8ba0cd chore(agents): Improve CLAUDE.md clarity and conciseness

Ubuntu:	1.48s (±0.05s) → 1.48s (±0.04s) · -0.01s (-0.4%)
macOS:	1.22s (±0.27s) → 1.21s (±0.20s) · -0.00s (-0.2%)
Windows:	1.82s (±0.42s) → 1.84s (±0.51s) · +0.01s (+0.7%)

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 517729d9-211f-4f6e-9a1b-7c12c6023f5f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The .agents/rules/base.md file was updated to streamline AI assistant guidelines. The inclusion: always frontmatter was removed, the detailed project overview was replaced with a shorter description, and multiple guideline sections were condensed or deleted, including dependency testing, PR review, and release note guidance.

Changes

Cohort / File(s)	Summary
AI Assistant Rules Documentation .agents/rules/base.md	Removed inclusion: always frontmatter; replaced detailed project overview with a brief description of Repomix; streamlined commit, PR, dependency, testing, and release note guidelines; reformatted coding guidance bullets into concise single-line directives.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• chore(rules): Configure AI agent rules and improve project guidelines #734 — Modifies .agents/rules/base.md with conflicting frontmatter and guideline changes in the same file.
• chore(config): consolidate AI assistant rules configuration #726 — Updates .agents/rules/base.md as part of consolidating and centralizing AI assistant rule files.
• feat(docs): Add AGENTS.md symlink for agents.md compatibility #832 — Creates a symlink to .agents/rules/base.md, directly referencing the file being modified.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The title refers to 'CLAUDE.md' but the actual file being modified is '.agents/rules/base.md', making it misleading and inaccurate.	Update the title to reference '.agents/rules/base.md' or use a more accurate description like 'chore(agents): Simplify base agent rules documentation'.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description is detailed and complete, covering all changes made and including a checklist with completed items matching the template requirements.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/improve-claude-md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

Code Review — Claude

Overall: Looks good. The simplification is well-executed — removing "The assistant shall" prefixes, consolidating sections, and referencing the PR template file instead of inlining it are all solid improvements. A few items worth noting:

Recommended

1. Missing language tag on commit example code block (line 59)
The fenced code block with commit examples lacks a language identifier, which triggers markdownlint MD040. Should be ```text instead of bare ```. (Also flagged by CodeRabbit.)

2. Airbnb Style Guide reference may be outdated
The guidelines say "Follow the Airbnb JavaScript Style Guide" but the project actually uses Biome for linting (biome.json, @biomejs/biome in devDependencies, npm run lint-biome). Consider updating to reference Biome directly, or at minimum noting that Biome is the enforced linter. (Also flagged by Gemini.)

Not Needed (from bot reviews)

• CodeRabbit's CHANGES_REQUESTED status: The only actionable item was the MD040 language tag — this doesn't warrant blocking the PR, just a minor fix.

Detailed analysis

What works well

• 27% line reduction while preserving all essential content
• Imperative voice is clearer and more natural for AI agent consumption
• PR template delegation to .github/pull_request_template.md is DRY
• inclusion: always removal is safe — no other agent rules use this field, and alwaysApply: true is the standard mechanism
• Adding JSON to supported output formats (second commit) is a good catch

Minor observations (no action needed)

• The removed PR Review Guidelines and Release Note Guidelines sections were generic enough that their absence is unlikely to degrade agent behavior. If specific review/release workflows are needed, they're better served by dedicated skill files.
• The style commit type example (style(website): Update GitHub sponsor button color) was removed from the examples block but style is still listed in the Types bullet, which is sufficient.
• The commit body guidance is now a bullet point rather than a subsection — less prominent but still discoverable.

Token efficiency

~140 fewer tokens when included in agent context. Small but meaningful over many invocations.

🤖 Generated with Claude Code

[claude]

Code Review — Claude (Follow-up)

Overall: Approve. The previous review feedback has been addressed — language tag added (commit 3) and JSON format included (commit 2). The simplification is clean and well-executed.

One remaining item (Recommended)

Airbnb Style Guide reference (line 44) — Still says "Follow the Airbnb JavaScript Style Guide" but the project uses Biome (biome.json, npm run lint-biome), OXLint (npm run lint-oxlint), and tsgo for type checking. This is a pre-existing inaccuracy carried forward, not introduced by this PR. Consider updating to something like:

- Follow the linting rules enforced by Biome and OXLint

This could be addressed here or in a follow-up — it shouldn't block merge.

Review agent summary

• Code quality: Clean markdown simplification. Consistent formatting, proper language tags on code blocks, good use of file references over inline duplication.
• Security: No concerns — documentation-only change with no security-relevant content removed.
• Performance: Net positive — ~37 fewer lines reduces token consumption in AI agent context windows.
• Test coverage: No tests needed for documentation changes.
• Conventions: Commit messages follow Conventional Commits with scope. Minor note: PR title references "CLAUDE.md" but the actual file is .agents/rules/base.md (this file is symlinked to CLAUDE.md, so the title is understandable).
• Holistic: PR achieves its stated goal of 27% reduction while preserving all essential content. The removed sections (PR Review Guidelines, Release Note Guidelines) were generic and are better served by dedicated skill files.

🤖 Generated with Claude Code