docs: update engineering convention docs#3079
Open
vseehausen wants to merge 6 commits into
Open
Conversation
Introduces a structured engineering convention manual under docs/engineering to capture and apply CGW-local code-review patterns: - rules.json + rules.schema.json: 59 durable pre-PR rules across modules, types, auth, database, cache, config, tests, performance, logging, security, and resilience. Each carries a stable rule ID, area, durable rule, executable check, exampleRefs, and reviewLearningIds. - rules.generated.md: human-readable view, regenerated from rules.json. - examples/: 12 topic files (testing, schemas-and-validation, cache, database-migrations, repositories-and-pagination, controllers-and-swagger, error-handling, auth-and-secrets, style, scope-and-pr-hygiene, resilience, configuration). Each Avoid/Prefer/Why block traces back to its source PR and review-learning ID. - working/review-learnings.json + schema: 31 review learnings distilled from CGW PR review feedback (CLOSED-20251211 through CLOSED-20260205). Every CLOSED-* learning carries the originating reviewCommentIds / reviewIds / issueCommentIds for traceability. - working/review-learning-ledger.json: covered-range state for the safe-engineering:code-conventions skill. - README.md and project-structure.md: routing and placement guide. - .gitignore: ignore docs/engineering/pr-self-review-checklist.generated.md produced by the PR-review checklist generator.
vseehausen
force-pushed
the
valentin/cgw-code-conventions-docs-only
branch
from
af21e83 to
26f2f6f
Compare
Adds RL-20260508-001 (HIST), a manual learning that captures the rule "push negative paths to the lowest layer that can prove the property; e2e proves wiring once per route, not per branch." - review-learnings.json: new RL-20260508-001 mapped to TEST-02. - rules.json: TEST-02 retitled "Right test layer (pyramid)"; rule and check expanded with the layer-routing decision and the wiring-vs- branch distinction; reviewLearningIds links the new entry. - rules.generated.md: regenerated.
…e2e flow Organizes the existing TEST-* rules and PR-sourced examples into a single decision-ordered reference. Sits alongside the per-rule index (rules.json) and the receipts library (examples/testing.md), not replacing them. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- conventions/ holds the action layer (project-structure.md, testing.md) — what devs and AI read when writing code. - sources/ holds the audit trail: rules.json, examples/, rules.generated.md, plus working/ (review-learnings, ledger, open-question-options) which only bot maintenance touches. - README at root explains the layout and routes tasks to the right doc. - Internal cross-refs in conventions/testing.md and README rewritten. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Forward-compound run over 11 closed PRs (189 comments). Adds 11 review learnings mapped to existing rules (AUTH-05, DB-02/03/05, MOD-02/05, TYPE-03/04, TEST-01/02) — tightening their rule/check text — plus one AUTH-05 example. No new rules; the existing set already covered them. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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
Validation