From d3c778f38454c903e6a18424b52fced090294e4e Mon Sep 17 00:00:00 2001 From: emeraldleaf Date: Fri, 5 Jun 2026 08:26:43 -0600 Subject: [PATCH] =?UTF-8?q?docs:=20post-encoding-loop=20refresh=20?= =?UTF-8?q?=E2=80=94=20README=20+=20dev-loop.md=20+=20dev-loop.svg?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three doc sites had drift from the recent encoding-loop work: README.md (line 18 "Two AI reviewers" callout) - Old: lists only .claude/skills/ as what Claude Code reads - New: lists the full .claude/ folder (agents, skills, slash commands, hook scripts, hook + permission wiring) — the meta-layer that gets ported between projects - ADDED a new "Continuous Rule Encoding" callout right after, introducing the loop + 3-tier enforcement spectrum + lean-CLAUDE.md discipline (~300 lines, CI soft cap 400, hard fail 500) + the 5 encoding surfaces + cross-links to /feature-spec, /article-audit, /check-rules, /new-feature-slice, /sync-status. Points at docs/dev-loop.md for full mechanics and docs/dev-loop-scaffolding.svg for the scaffolding diagram. docs/dev-loop.md (Slash commands table) - Was missing /feature-spec (just landed in #115) and /article-audit (landed earlier this week) - Added both with their actual one-line descriptions docs/dev-loop.svg (rendered diagram people see on GitHub) - Stage 1 "PostToolUse" hooks list: added check-file-moves.sh (the hook added in #114 for git-mv/git-rm detection) - Stage 1 "Slash commands" list: added /feature-spec and /article-audit alongside the existing 3; shifted Agents/Skills/Secondary-reviewer positions down by 54px to make room - Encoding loop "Encode in:" footer: was 4 surfaces (CLAUDE.md + .coderabbit.yaml + arch-reviewer Pattern Checklist + skill), now 5 surfaces (added "docs + paired diagrams" as surface 5, shortened labels to fit). Title now reads "Encode in 1+ of 5 surfaces" to clarify the surface count What this is NOT: - Not a full dev-loop.svg regeneration — the SVG also has other minor staleness (CLAUDE.md size annotation "25 KB" is outdated since the trim; integration tests list only shows Catalog + Order while CI now runs 4 slices). Targeted surgery here, not a rewrite. Verification: - broken-link guard: exit 0 on the changed markdown files - All cross-references resolve Co-Authored-By: Claude Opus 4.7 --- README.md | 3 ++- docs/dev-loop.md | 2 ++ docs/dev-loop.svg | 63 +++++++++++++++++++++++++---------------------- 3 files changed, 38 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 8f1d803c..6106d240 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,8 @@ NextAurora demonstrates a production-style distributed system with event-driven > - **Two database engines on purpose.** **CatalogService** + **ShippingService** run on **PostgreSQL** (Npgsql); **OrderService** + **PaymentService** run on **SQL Server** (Microsoft.Data.SqlClient). NotificationService is stateless. The split exercises both EF Core providers and the per-provider primitives the architecture leans on: **Postgres `xmin`** (system column, no schema change) vs **SQL Server `rowversion`** (real column, requires migration) for optimistic-concurrency tokens; **Wolverine's `PersistMessagesWithPostgresql` vs `PersistMessagesWithSqlServer`** for the transactional outbox; **`DistributedLock.SqlServer` (`sp_getapplock`)** for the PaymentRecoveryJob sweeper. > **How it was built — AI-assisted, multi-model review, verification at every layer.** -> - **Two AI reviewers, not one.** [Claude Code](https://claude.com/claude-code) (Opus 4.7) is the primary pair-programmer — reads [`CLAUDE.md`](CLAUDE.md), the project-specific [`.claude/skills/`](.claude/skills/) (e.g. the `dotnet-performance` skill loaded for EF Core review, `excalidraw-diagram` for architecture visuals), and a persistent project memory. **GitHub Copilot (GPT-5)** sits in-editor for second-opinion diff review, with project conventions encoded in [`.github/copilot-instructions.md`](.github/copilot-instructions.md). Disagreement between the two is treated as a signal to dig deeper, not pick the louder voice. The principle is not "AI wrote it" — it's *two models + a human author + automated checks all sign off before merge*. The working loop: implement → run unit + integration tests → cross-model review → fix → commit. +> - **Two AI reviewers, not one.** [Claude Code](https://claude.com/claude-code) (Opus 4.7) is the primary pair-programmer — reads [`CLAUDE.md`](CLAUDE.md) plus the [`.claude/`](.claude/) folder beside it (agents, [skills](.claude/skills/), [slash commands](.claude/commands/), hook scripts, hook + permission wiring) every session, and a persistent project memory. **GitHub Copilot (GPT-5)** sits in-editor for second-opinion diff review, with project conventions encoded in [`.github/copilot-instructions.md`](.github/copilot-instructions.md). Disagreement between the two is treated as a signal to dig deeper, not pick the louder voice. The principle is not "AI wrote it" — it's *two models + a human author + automated checks all sign off before merge*. The working loop: implement → run unit + integration tests → cross-model review → fix → commit. +> - **Continuous Rule Encoding — the compounding feedback loop.** Every meaningful finding (CodeRabbit catch, test failure, architecture-reviewer agent flag, manual code review, prod incident, even community articles audited via [`/article-audit`](.claude/commands/article-audit.md)) gets the question: *"could the next person repeat this?"* If yes, the rule gets written down at the right tier of an enforcement spectrum — **Convention** (CLAUDE.md + `.claude/`), **PR-review automation** ([`.coderabbit.yaml`](.coderabbit.yaml) + the [architecture-reviewer agent](.claude/agents/architecture-reviewer.md)), or **Mechanical** (build-fail / hook-block / CI-grep). Rules move down the spectrum as they prove their value — the looser the tier, the more you rely on noticing, and noticing always degrades first. CLAUDE.md itself stays lean (~300 lines; CI-guarded soft cap at 400, hard fail at 500); deep dives live in [`docs/`](docs/) and the [`dotnet-performance` skill](.claude/skills/dotnet-performance/SKILL.md). New features run through [`/feature-spec`](.claude/commands/feature-spec.md), which drafts the structured handoff (goal + acceptance + auto-referenced CLAUDE.md constraints) so the spec → implementation → encoding loop stays closed. Full mechanics + the 5 encoding surfaces: [`docs/dev-loop.md`](docs/dev-loop.md); scaffolding diagram: [`docs/dev-loop-scaffolding.svg`](docs/dev-loop-scaffolding.svg). > - **Verification at every layer.** Build: `TreatWarningsAsErrors` + four build-time analyzers (Meziantou, SonarAnalyzer.CSharp, Roslynator, BannedApiAnalyzers — the last rejects concrete concurrency hazards at compile). Tests: 100+ unit + integration tests, with integration slices for all four DB-touching services via [Testcontainers](https://dotnet.testcontainers.org/) — Catalog (Postgres + Redis), Order (SQL Server + stubbed Wolverine transport), Payment (SQL Server), Shipping (Postgres). Each slice runs as its own step in CI so a single-slice failure doesn't mask the rest. CI: GitHub Actions runs build + tests + Coverlet/Cobertura coverage on every PR. Security: CodeQL on every push + weekly schedule. Dependencies: Dependabot weekly NuGet bumps (grouped per ecosystem). Local dev: Aspire orchestrates Postgres / SQL Server / Service Bus emulator / Redis / Keycloak in Docker so integration issues surface *before* push. > - **Testing strategy was decided upfront, not retrofitted.** Unit tests cover handlers + domain rules with mocked infrastructure (NSubstitute, FakeTimeProvider). Integration tests use live containers to prove what mocks can't: EF migrations apply cleanly to fresh DBs, HybridCache actually invalidates on write, the `xmin` / `RowVersion` concurrency tokens actually fire under racing writes, Wolverine's transactional outbox + saga handlers actually persist and dispatch. Cross-service E2E over a live Azure Service Bus wire is tracked as deferred in [STATUS.md](docs/STATUS.md). Open issues and other deferred cleanups live there too. diff --git a/docs/dev-loop.md b/docs/dev-loop.md index 7e745d9c..e9a4945a 100644 --- a/docs/dev-loop.md +++ b/docs/dev-loop.md @@ -164,6 +164,8 @@ This is where most code originates. The tooling here shapes proposed edits | Command | Purpose | |---|---| | [/new-feature-slice](../.claude/commands/new-feature-slice.md) | Scaffolds a VSA feature slice matching the [OrderService/Features/PlaceOrder.cs](../OrderService/Features/PlaceOrder.cs) canonical shape. | +| [/feature-spec](../.claude/commands/feature-spec.md) | Drafts a structured feature spec (goal + acceptance + auto-referenced CLAUDE.md constraints) — the handoff between intent and implementation. Feeds the encoding loop. | +| [/article-audit](../.claude/commands/article-audit.md) | Audits an external article (community blog, post, conference talk) against CLAUDE.md and the encoding surfaces — outputs a coverage map + verdict + draft issue body for any gaps. | | [/sync-status](../.claude/commands/sync-status.md) | Refreshes STATUS.md from `git log` + open issues. | | [/check-rules](../.claude/commands/check-rules.md) | Audits every `See CLAUDE.md` paraphrase against the canonical rule and flags drift. | diff --git a/docs/dev-loop.svg b/docs/dev-loop.svg index c3db6d64..c29e7018 100644 --- a/docs/dev-loop.svg +++ b/docs/dev-loop.svg @@ -76,27 +76,30 @@ PreToolUse: block-sync-over-async.sh SessionStart: inject-status.sh PostToolUse: check-claude-md-refs.sh - - Slash commands (manual) - /new-feature-slice - /sync-status - /check-rules - - Agents (manual) - architecture-reviewer - - Skills (auto-trigger on intent) - verification-before-completion - systematic-debugging - test-driven-development - variant-analysis - writing-plans + executing-plans - using-git-worktrees - skill-security-auditor - dotnet-performance, excalidraw-diagram - - Secondary reviewer (in-editor) - GitHub Copilot (GPT-5) + PostToolUse: check-file-moves.sh + + Slash commands (manual) + /new-feature-slice + /feature-spec + /article-audit + /sync-status + /check-rules + + Agents (manual) + architecture-reviewer + + Skills (auto-trigger on intent) + verification-before-completion + systematic-debugging + test-driven-development + variant-analysis + writing-plans + executing-plans + using-git-worktrees + skill-security-auditor + dotnet-performance, excalidraw-diagram + + Secondary reviewer (in-editor) + GitHub Copilot (GPT-5) @@ -246,14 +249,16 @@ Finding → - Encode in: - CLAUDE.md - + - .coderabbit.yaml path_instructions - + - architecture-reviewer Pattern Checklist - + - skill (if procedural) + Encode in 1+ of 5 surfaces: + CLAUDE.md + + + .coderabbit.yaml + + + arch-reviewer agent + + + skill/command + + + docs + paired diagrams Next cycle →