docs: structure the enumerations in the architecture rule pages - #351
Conversation
Fourth pass. This category is different from correctness, and the diff is smaller because of it: most of the length here is doing work — the `Card.v2` worked example, the `**`-asymmetry rule, the argument for why a reserved vocabulary is only enforceable in some positions. Compressing those would cost the reader more than the words do. So this only converts prose that was already a list into a list: the five inertness cases, the "two things never reported" pairs, the specificity ordering, and the three rules' differing definitions of PascalCase. Same sentences, arranged so a reader checking one case can find it. - architecture en paragraphs over 55 words: 22 -> 14 - architecture ja paragraphs over 220 characters: 15 -> 8 The 14 that remain are the explanatory ones, left deliberately. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
Warning Review limit reached
Next review available in: 29 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (6)
📝 WalkthroughWalkthroughThe documentation for three architecture rules now clarifies naming criteria, glob configuration and precedence, finding locations, override behavior, and unmatched exclusions in English and Japanese. ChangesArchitecture rule documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/src/content/docs/rules/architecture/directory-naming.md`:
- Around line 68-76: Replace the fixed rule count with wording meaning “these
rules” in both affected sections: update
docs/src/content/docs/rules/architecture/directory-naming.md lines 68-76 from
“The three rules,” and update
docs/src/content/docs/ja/rules/architecture/directory-naming.md lines 68-76 from
“3 つのルール” to equivalent count-independent wording.
In `@docs/src/content/docs/rules/architecture/reserved-directory-names.md`:
- Around line 132-139: Clarify the same-glob collision description so it states
that both map entries must contain at least one name; empty values follow the
separate empty-value path. Apply this wording to the English section in
docs/src/content/docs/rules/architecture/reserved-directory-names.md (lines
132-139) and the corresponding Japanese section in
docs/src/content/docs/ja/rules/architecture/reserved-directory-names.md (lines
134-141).
In `@docs/src/content/docs/rules/architecture/unit-entry-file.md`:
- Around line 38-42: The descriptions in
docs/src/content/docs/rules/architecture/unit-entry-file.md lines 38-42 and
docs/src/content/docs/ja/rules/architecture/unit-entry-file.md lines 39-42
should distinguish permissive validation from the resulting finding: state that
the missing leading dot is accepted during configuration validation, but causes
the rule to report a missing entry file when the constructed filename cannot be
found. Apply the equivalent clarification in Japanese while preserving the
existing examples and surrounding explanation.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: dc8c0ce1-adfd-4662-a935-f5c4bc10c29c
📒 Files selected for processing (6)
docs/src/content/docs/ja/rules/architecture/directory-naming.mddocs/src/content/docs/ja/rules/architecture/reserved-directory-names.mddocs/src/content/docs/ja/rules/architecture/unit-entry-file.mddocs/src/content/docs/rules/architecture/directory-naming.mddocs/src/content/docs/rules/architecture/reserved-directory-names.mddocs/src/content/docs/rules/architecture/unit-entry-file.md
All three pre-existing; the restructure put them where they read as wrong. - "The three rules" hard-codes a count, which AGENTS.md bans for exactly this reason. The names below it are the durable reference. - The same-glob collision is only reported when **both** map values name at least one directory (reserved-directory-names.ts:142-144). An empty value is dropped before matching, so the other side governs alone and the empty-value reason reports instead. - "A missing dot fails silently" was backwards: config validation passes, and the rule then reports a missing entry file for a directory that has one. Confusing, but not silent — and the distinction is what tells a reader where to look. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1 participant
Fourth pass, after #347 (code comments), #348 (guides) and #350 (correctness rules).
This one is deliberately a smaller diff
architectureis not likecorrectness. Where correctness had run-on "Not flagged: A, B, C, D, E, F" sentences that were pure padding, most of the length here is doing work — theCard.v2worked example that shows why two rules answer differently about the same directory, the**-between-segments asymmetry, the argument for why a reserved vocabulary is only enforceable at positions whose children are a closed list.Compressing those would cost the reader more than the words do. So this PR converts only prose that was already a list into a list, and leaves the explanation alone.
The 14 that remain are the explanatory ones, and they are meant to stay.
What changed
Four shapes, all the same move:
reserved-directory-names— five semicolon-separated clauses a reader had to count through to find their own → five bullets.overridesexception nested where it belongs.unit-entry-file— "more path segments first, then fewer**segments, then the longer key, then the alphabetically first" → a numbered list, since it is literally an ordered tiebreak.directory-naming— a paragraph comparing three things → three bullets and a one-line conclusion.No sentence lost a fact; they were rearranged so a reader checking one case can find that case.
Safety
en and ja edited together, frontmatter untouched.
blume check, docs build,pnpm testandpnpm lintall pass.Remaining
performance (12 en / 10 ja), security (2 / 3).
seoneeds nothing.🤖 Generated with Claude Code
Summary by CodeRabbit
overridesand unmatched exclusions.