docs: restructure CLAUDE.md into governance core + modular playbooks#30
Merged
Conversation
Refactor project instructions based on AI agent engineering review to improve signal-to-noise ratio, enforce clearer boundaries, and reduce agent cognitive load. Key changes to CLAUDE.md: - Add Machine Rules Quick Reference (P0/P1/P2 severity model) - Add Source of Truth Priority hierarchy (5-tier conflict resolution) - Add Required task response structure for non-trivial tasks - Add Uncertainty Protocol — never invent endpoints, event names, DTO fields - Add decision protocol for blocked situations (4-step escalation) - Add bidirectional navigation rule for all doc files - Add pre-mark-done verification checklist - Add anti-context-poisoning rule to Agent Integrity Rules - Add migration complexity escalation rule (multi-tenant high-blast-radius paths) - Add cross-module hard stops (no Infrastructure ref, no cross-table query) - Add execution-critical path discipline for WorkflowEngine hot paths - Add projection-first rule for EF list queries - Add reading priority hierarchy with token-aware re-read guidance - Strengthen scope discipline (flag don't silently fix) - Add anti-overengineering: concrete first, no abstractions without 2 use cases - Add respect-existing-conventions rule - Soften anti-overengineering to allow proven architectural abstractions - Update no-var rule with target-typed new guidance - Add hotfix exception for docs-first rule Moved to docs/playbooks/: - docs/PROCESS.md → docs/playbooks/process.md - docs/PATTERNS.md → docs/playbooks/patterns.md New playbooks: - docs/playbooks/testing.md — full test isolation, naming, mocking rules - docs/playbooks/frontend.md — TanStack Query, TypeScript, routing, render boundaries - docs/playbooks/wireframes.md — component kit template rules (from CLAUDE.md) All playbooks have bidirectional navigation links back to docs/README.md and CLAUDE.md. CLAUDE.md condensed Testing and Frontend sections to summaries with pointers. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThis PR refines the core machine rules in ChangesDocumentation Standards and Process Framework
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/playbooks/process.md (1)
83-84:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winUpdate stale
docs/PATTERNS.mdreferences to the new playbook path.Lines 83 and 123 still point to
docs/PATTERNS.md, but the file was moved todocs/playbooks/patterns.md. These links should be updated to avoid broken navigation.Suggested patch
-- If a new pattern was established: add to `docs/PATTERNS.md` +- If a new pattern was established: add to `docs/playbooks/patterns.md` ... -- If a new frontend pattern was established: add to `docs/PATTERNS.md` +- If a new frontend pattern was established: add to `docs/playbooks/patterns.md`Also applies to: 123-124
🤖 Prompt for 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. In `@docs/playbooks/process.md` around lines 83 - 84, Update the stale links that point to docs/PATTERNS.md to the new path docs/playbooks/patterns.md within the playbook file (both occurrences around the current lines referencing patterns, e.g., the list item "- If a new pattern was established: add to `docs/PATTERNS.md`"); change those references to `docs/playbooks/patterns.md` (preserve backticks and case exactly as the target filename) so navigation points to the moved file.
🤖 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/playbooks/patterns.md`:
- Around line 3-5: Remove the blank line inside the leading blockquote in
docs/playbooks/patterns.md so the two quoted lines are adjacent and MD028 is
satisfied: edit the header block that contains the "**Navigation**: [←
docs/README.md](../README.md) · [← CLAUDE.md](../../CLAUDE.md)" line and the
long guidance line (the paragraph starting "Read this file when the task
involves...") and join them without an empty line between, or collapse the
blockquote to a single line if that preserves intended formatting.
In `@docs/playbooks/process.md`:
- Around line 3-5: Fix the MD028 markdownlint error by removing the empty blank
line inside the blockquote: merge the two quoted lines ("**Navigation**: [←
docs/README.md](../README.md) · [← CLAUDE.md](../../CLAUDE.md)" and
"Step-by-step checklists for backend and frontend. Read this at the start of any
new module or user story — before writing any code.") so the blockquote has no
blank line between them.
In `@docs/playbooks/testing.md`:
- Around line 33-34: Replace the soft-exemption sentence "Integration tests
(requiring Docker) can be skipped unless explicitly instructed." with a
blocker/escalation rule: update the line that follows the `dotnet test
unit-tests.slnf` instruction to state that integration tests requiring Docker
are mandatory and, if Docker is unavailable, developers must stop work and
report a blocker (escalate to the team/CI owner) rather than skipping tests;
ensure the wording enforces “no exceptions” and references integration
tests/Docker explicitly so the policy is unambiguous.
In `@docs/README.md`:
- Around line 3-5: The blockquote in the docs README has a blank line between
the quoted lines causing MD028; edit the blockquote so the quoted lines are
contiguous by removing the empty line between the "**Navigation**: [←
CLAUDE.md](../CLAUDE.md)" line and the "A low-code SaaS platform for building
data-driven workflow applications." line (i.e., make them back-to-back within
the same blockquote).
---
Outside diff comments:
In `@docs/playbooks/process.md`:
- Around line 83-84: Update the stale links that point to docs/PATTERNS.md to
the new path docs/playbooks/patterns.md within the playbook file (both
occurrences around the current lines referencing patterns, e.g., the list item
"- If a new pattern was established: add to `docs/PATTERNS.md`"); change those
references to `docs/playbooks/patterns.md` (preserve backticks and case exactly
as the target filename) so navigation points to the moved file.
🪄 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: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 3a7dbbe9-a8c4-4fc1-9080-300c889da790
📒 Files selected for processing (7)
CLAUDE.mddocs/README.mddocs/playbooks/frontend.mddocs/playbooks/patterns.mddocs/playbooks/process.mddocs/playbooks/testing.mddocs/playbooks/wireframes.md
Comment on lines
+3
to
5
| > **Navigation**: [← docs/README.md](../README.md) · [← CLAUDE.md](../../CLAUDE.md) | ||
|
|
||
| > Read this file when the task involves any of: adding/updating NuGet packages, EF Core aggregate or JSONB mapping, Minimal API endpoint wiring, writing tests, implementing a list/query endpoint, adding async methods, defining response DTOs, writing repository methods, adding domain methods to an aggregate, working with multi-tenant raw SQL, Wolverine handlers or jobs, implementing a new step or field type, adding a cross-cutting concern, or any design decision about where logic should live. Skip otherwise. |
There was a problem hiding this comment.
Remove blank line inside blockquote in file header.
Line 4 violates markdownlint MD028. Keep the two quoted lines adjacent (or drop blockquote formatting on one line).
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 4-4: Blank line inside blockquote
(MD028, no-blanks-blockquote)
🤖 Prompt for 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.
In `@docs/playbooks/patterns.md` around lines 3 - 5, Remove the blank line inside
the leading blockquote in docs/playbooks/patterns.md so the two quoted lines are
adjacent and MD028 is satisfied: edit the header block that contains the
"**Navigation**: [← docs/README.md](../README.md) · [←
CLAUDE.md](../../CLAUDE.md)" line and the long guidance line (the paragraph
starting "Read this file when the task involves...") and join them without an
empty line between, or collapse the blockquote to a single line if that
preserves intended formatting.
Comment on lines
+3
to
5
| > **Navigation**: [← docs/README.md](../README.md) · [← CLAUDE.md](../../CLAUDE.md) | ||
|
|
||
| > Step-by-step checklists for backend and frontend. Read this at the start of any new module or user story — before writing any code. |
There was a problem hiding this comment.
Fix blockquote spacing to satisfy markdownlint.
Line 4 introduces MD028 (blank line inside blockquote). Remove the blank line between quoted header lines.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 4-4: Blank line inside blockquote
(MD028, no-blanks-blockquote)
🤖 Prompt for 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.
In `@docs/playbooks/process.md` around lines 3 - 5, Fix the MD028 markdownlint
error by removing the empty blank line inside the blockquote: merge the two
quoted lines ("**Navigation**: [← docs/README.md](../README.md) · [←
CLAUDE.md](../../CLAUDE.md)" and "Step-by-step checklists for backend and
frontend. Read this at the start of any new module or user story — before
writing any code.") so the blockquote has no blank line between them.
Comment on lines
+33
to
+34
| Run `dotnet test unit-tests.slnf` before every commit. When adding a new unit test project, add it to `unit-tests.slnf`. Integration tests (requiring Docker) can be skipped unless explicitly instructed. | ||
|
|
There was a problem hiding this comment.
Line 33 weakens the mandatory test gate and conflicts with repo policy.
The “integration tests can be skipped unless explicitly instructed” clause creates an exception path that contradicts the project’s no-exception testing discipline. Please replace it with blocker/escalation wording (e.g., Docker unavailable ⇒ stop and report blocker), not skip-by-default.
Proposed doc fix
-Run `dotnet test unit-tests.slnf` before every commit. When adding a new unit test project, add it to `unit-tests.slnf`. Integration tests (requiring Docker) can be skipped unless explicitly instructed.
+Run `dotnet test unit-tests.slnf` before every commit. When adding a new unit test project, add it to `unit-tests.slnf`. Integration tests (requiring Docker) are mandatory on affected changes; if Docker is unavailable, treat it as a blocker and escalate—do not skip by default.Based on learnings: "TDD is mandatory—write tests first, must pass before moving to next step. Applies to both .NET and frontend. No exceptions."
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Run `dotnet test unit-tests.slnf` before every commit. When adding a new unit test project, add it to `unit-tests.slnf`. Integration tests (requiring Docker) can be skipped unless explicitly instructed. | |
| Run `dotnet test unit-tests.slnf` before every commit. When adding a new unit test project, add it to `unit-tests.slnf`. Integration tests (requiring Docker) are mandatory on affected changes; if Docker is unavailable, treat it as a blocker and escalate—do not skip by default. |
🤖 Prompt for 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.
In `@docs/playbooks/testing.md` around lines 33 - 34, Replace the soft-exemption
sentence "Integration tests (requiring Docker) can be skipped unless explicitly
instructed." with a blocker/escalation rule: update the line that follows the
`dotnet test unit-tests.slnf` instruction to state that integration tests
requiring Docker are mandatory and, if Docker is unavailable, developers must
stop work and report a blocker (escalate to the team/CI owner) rather than
skipping tests; ensure the wording enforces “no exceptions” and references
integration tests/Docker explicitly so the policy is unambiguous.
Comment on lines
+3
to
5
| > **Navigation**: [← CLAUDE.md](../CLAUDE.md) | ||
|
|
||
| > A low-code SaaS platform for building data-driven workflow applications. |
There was a problem hiding this comment.
Fix blockquote lint violation in navigation header.
Line 4 creates a blank line inside a blockquote (MD028). Remove the blank line or keep the quoted lines contiguous so markdownlint passes.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 4-4: Blank line inside blockquote
(MD028, no-blanks-blockquote)
🤖 Prompt for 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.
In `@docs/README.md` around lines 3 - 5, The blockquote in the docs README has a
blank line between the quoted lines causing MD028; edit the blockquote so the
quoted lines are contiguous by removing the empty line between the
"**Navigation**: [← CLAUDE.md](../CLAUDE.md)" line and the "A low-code SaaS
platform for building data-driven workflow applications." line (i.e., make them
back-to-back within the same blockquote).
This was referenced May 16, 2026
This was referenced May 28, 2026
This was referenced Jun 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/PROCESS.md→docs/playbooks/process.mdanddocs/PATTERNS.md→docs/playbooks/patterns.mdtesting.md,frontend.md,wireframes.md— each with bidirectional navigation links back todocs/README.mdandCLAUDE.mdKey additions to CLAUDE.md
.Select()before.ToListAsync()— no entity materialisation on list pathsPlaybook structure
Test plan
← docs/README.md,← CLAUDE.md)docs/README.mdnavigation table includes all 5 playbooksdocs/playbooks/process.md,docs/playbooks/patterns.md)🤖 Generated with Claude Code
Summary by CodeRabbit