Skip to content

docs(claude): fix stale reference-template paths in Test structure rule#110

Merged
emeraldleaf merged 1 commit into
mainfrom
docs/claude-md-fix-stale-test-exemplars
Jun 4, 2026
Merged

docs(claude): fix stale reference-template paths in Test structure rule#110
emeraldleaf merged 1 commit into
mainfrom
docs/claude-md-fix-stale-test-exemplars

Conversation

@emeraldleaf
Copy link
Copy Markdown
Owner

@emeraldleaf emeraldleaf commented Jun 4, 2026

Summary

`CLAUDE.md` "Testing → Test structure" cited three reference templates; two had paths that don't exist on disk. `docs/dev-loop.md`'s "AAA with narrative comments" row paraphrased the same rule and inherited the same dead links.

Old (broken) New (exists)
`tests/OrderService.Tests.Unit/Application/PaymentFailedHandlerTests.cs` `tests/OrderService.Tests.Integration/OrderSagaTests.cs`
`tests/ShippingService.Tests.Unit/Application/GetShipmentByOrderHandlerTests.cs` `tests/OrderService.Tests.Unit/Domain/OrderTests.cs`
`tests/CatalogService.Tests.Integration/ProductAuthorizationTests.cs` (kept — exists)

Why

Surfaced by a `/check-rules` audit pass over all 30 `See CLAUDE.md` paraphrase sites. Unusual inversion: the canonical was the broken one. The paraphrase in `.claude/agents/architecture-reviewer.md:141` already cited real, working files (`OrderSagaTests.cs`, `OrderTests.cs`) — those were the substitutes used here.

What changed

  • CLAUDE.md:251 — three exemplars updated, one rephrased ("unit-tier IDOR" → "aggregate state-machine invariants, unit-tier" since IDOR really wants the integration tier).
  • docs/dev-loop.md:271 — same three citations updated to match.

No rule semantics changed

Just citations. The rule text ("AAA with narrative comments", required markers, story-comment convention, multi-invariant numbering) is unchanged. `/check-rules` should now show all 30 paraphrase sites aligned with no broken cross-references.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Updated testing guidance examples to reference current test implementations for the AAA (Arrange-Act-Assert) with narrative comments pattern.

CLAUDE.md "Testing → Test structure" cited three reference templates;
two had paths that don't exist on disk:
  - tests/OrderService.Tests.Unit/Application/PaymentFailedHandlerTests.cs
  - tests/ShippingService.Tests.Unit/Application/GetShipmentByOrderHandlerTests.cs

docs/dev-loop.md's "AAA with narrative comments" row paraphrased the same
rule and inherited the same dead links.

Surfaced by a /check-rules audit pass — the canonical was the broken one;
the paraphrase in .claude/agents/architecture-reviewer.md already cited
real, working templates (OrderSagaTests.cs, OrderTests.cs).

Replace with three templates that exist and exercise the three patterns:
  - ProductAuthorizationTests.cs — IDOR-prevention + rejected writes (kept)
  - OrderSagaTests.cs — saga consume-side idempotency under at-least-once
  - OrderTests.cs — aggregate state-machine invariants, unit-tier domain-only

No rule text changes; only the cited exemplars.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@emeraldleaf emeraldleaf merged commit b67ad63 into main Jun 4, 2026
4 of 5 checks passed
@emeraldleaf emeraldleaf deleted the docs/claude-md-fix-stale-test-exemplars branch June 4, 2026 03:14
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Jun 4, 2026

Review Change Stack

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 8cc37225-354d-4076-b601-1b0ea82eef69

📥 Commits

Reviewing files that changed from the base of the PR and between 9454e6d and d50e884.

📒 Files selected for processing (2)
  • CLAUDE.md
  • docs/dev-loop.md

Walkthrough

This PR updates documentation references for the "AAA with narrative comments" testing pattern across two files. Both CLAUDE.md and docs/dev-loop.md have their example test template links changed from payment/shipment handler examples to order saga and order unit-domain examples, keeping the pattern guidance text unchanged.

Changes

Test Documentation Pattern References

Layer / File(s) Summary
AAA with narrative comments template references
CLAUDE.md, docs/dev-loop.md
Updated the example test template references for the "AAA with narrative comments" required testing pattern, replacing PaymentFailedHandlerTests.cs and GetShipmentByOrderHandlerTests.cs with OrderSagaTests.cs and OrderTests.cs while keeping the pattern guidance text unchanged.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Possibly related PRs

  • emeraldleaf/NextAurora#54: Both PRs update the documentation's "AAA with narrative comments" required-test-pattern template references in the same files, adjusting which example test files are referenced.
  • emeraldleaf/NextAurora#27: Both PRs update the documentation guidance for the Testing workflow in CLAUDE.md and docs/dev-loop.md, with this PR adjusting example template test references.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/claude-md-fix-stale-test-exemplars

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

@codecov
Copy link
Copy Markdown

codecov Bot commented Jun 4, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant