docs: Refresh CLAUDE.md with AGENTS.md v16.0 strategic principles and tech debt management
Updates: - Add governance section referencing AGENTS.md v16.0 decision criteria - Replace coding standards with Work Decision Checklist (13 items) - Integrate AI input packet (8-item verification before code request) - Reinforce blocking rules with anti-patterns (10 explicit blockers) - Add Tech Debt Management section (registry, impact/effort matrix, paydown target) - Update Validation Gates with status tracking This ensures CLAUDE.md stays synchronized with project governance and guides all AI-assisted work toward architectural excellence, not convenience. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -2,6 +2,17 @@
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## ⚖️ Governance: AGENTS.md v16.0 Strategic Principles
|
||||
|
||||
**All work — code changes, refactors, new features, tooling — must follow AGENTS.md v16.0 guidelines:**
|
||||
|
||||
- **13 Decision Criteria:** SOLID, complexity, data integrity, necessity-driven, normalization, simplicity, patterns, guardrails, traceability, reliability, maturity, right-way, tech debt
|
||||
- **Work Checklist:** Every task must self-assess against 13-item decision framework before implementation
|
||||
- **Anti-Patterns (Blockers):** Never gold-plate, never skip testing, never SELECT *, never magic numbers, never direct module-to-module table access
|
||||
- **Tech Debt:** Recorded in registry with Impact/Effort; 20% quarterly paydown target
|
||||
|
||||
**Reference:** See `AGENTS.md` section "v16.0 Strategic Architecture & Engineering Excellence" for full framework.
|
||||
|
||||
## Project Overview
|
||||
|
||||
**K-ArtSell Aegis v16.0** is a complex financial/investment advisory system built on a **Modular Monolith** with **Vertical Slice** architecture. It enforces strict execution completeness, evidence preservation, and controlled model operations—not production-ready until all validation gates (252+ trading days shadow, OOS testing, PBO/DSR verification) pass.
|
||||
@@ -390,33 +401,56 @@ pnpm exec playwright test --headed # Run with browser UI
|
||||
|
||||
## Guardrails & Anti-Patterns
|
||||
|
||||
### Coding Standards (from VIBE_CODING_GUARDRAILS.md)
|
||||
### ✅ Work Decision Checklist (from AGENTS.md v16.0)
|
||||
|
||||
**Before requesting code changes, ensure these 8 inputs are present:**
|
||||
1. **Source:** Reference policy, ADR, data contract, requirement ID
|
||||
2. **Slice Spec:** User goal, non-goal, state transitions, RBAC
|
||||
3. **Screen Spec:** Component tree, state management, a11y
|
||||
4. **Contract:** Endpoint paths, event schemas, HTTP status codes, ETag/idempotency handling
|
||||
5. **Data:** Schema, columns, PIT conditions, migration, index plan
|
||||
6. **Tests:** Unit/integration/data/E2E/Golden scenarios + failure cases
|
||||
7. **Ops:** Metrics, alerts, runbooks, rollback procedure, on-call owner
|
||||
8. **Output Rule:** Changed files, commands to verify, assumptions, residual risks
|
||||
Before writing code, verify:
|
||||
|
||||
### Blocking Rules
|
||||
- **No undocumented policy IDs or thresholds.** Every numeric constant must trace to a requirement.
|
||||
- **Pending decisions:** Mark with `DECISION_REQUIRED` or `DESIGN_PROPOSAL` comment.
|
||||
- **One PR = one slice or one refactoring goal.** No mixing feature work + unrelated cleanup.
|
||||
- **Feature changes ≠ refactoring.** Separate PRs: feature, then refactoring, then verify.
|
||||
- **Never hide failing/skipped tests.** If a test fails, fix it or raise an issue.
|
||||
- **SQL review:** Generated SQL must pass schema owner review, PIT validation, index analysis.
|
||||
- **Algorithm changes:** Never merge without Golden/Frozen OOS diff showing no regression.
|
||||
- **Real customer data:** Never include in prompts, fixtures, or logs.
|
||||
- [ ] **SOLID:** Single responsibility? Dependency inversion? Substitutable abstractions?
|
||||
- [ ] **Complexity:** Cyclomatic complexity ≤ 10 per method? (Policy exceptions allowed)
|
||||
- [ ] **Audit:** Evidence/Revision tracked? PIT query present? `published_at <= cutoff`?
|
||||
- [ ] **Necessity:** Grounded in requirement/ADR/issue? Not "might need later"?
|
||||
- [ ] **Normalization:** Writes are 3NF + append + revision? Reads use denormalized projections?
|
||||
- [ ] **Simplicity:** Top→bottom readability? No hidden assumptions? No magic values?
|
||||
- [ ] **Pattern:** Follows Vertical Slice / Job / Component standard? Approved contract?
|
||||
- [ ] **Guardrails:** Source/Assumption/Decision documented? AI decisions traced?
|
||||
- [ ] **Traceability:** Artifact preserved? Reproducible? Linked to ADR/Issue/Debt ID?
|
||||
- [ ] **Safety:** Idempotent? Rollback-safe? Failure modes handled? No partial success?
|
||||
- [ ] **Maturity:** Contract/schema/test BEFORE implementation? No placeholders merged?
|
||||
- [ ] **Right Way:** No shortcuts (--no-verify, force push)? Root cause fixed? Code reviewed?
|
||||
- [ ] **Debt:** Tech debt registered with ID? Paydown target met? No new unbounded debt?
|
||||
|
||||
### AI Input Packet (from VIBE_CODING_GUARDRAILS.md)
|
||||
|
||||
**Before requesting code from Claude, provide all 8:**
|
||||
|
||||
1. **Source:** Policy ID, ADR, requirement, data contract, reference implementation
|
||||
2. **Slice Spec:** User goal, non-goal, state transitions, RBAC constraints
|
||||
3. **Screen Spec:** Component tree, state ownership, a11y requirements
|
||||
4. **Contract:** Endpoint path/verb, event schema, status codes, idempotency, ETag handling
|
||||
5. **Data:** Schema (3NF write model), columns, PIT conditions, migration strategy, index plan
|
||||
6. **Tests:** Unit/integration/data/E2E/Golden scenarios, failure cases, replay scenarios
|
||||
7. **Ops:** Metrics, alerts, runbook, rollback procedure, owner/secondary
|
||||
8. **Output Rule:** Changed files, verification commands, assumptions, residual risks
|
||||
|
||||
### Blocking Rules (Non-Negotiable)
|
||||
|
||||
- ❌ **No gold-plating:** Every line must serve a requirement. "Might need later" is debt, not code.
|
||||
- ❌ **No undocumented magic:** Policy IDs, thresholds, DB columns must trace to approved source.
|
||||
- ❌ **No mixed concerns:** One PR = one Vertical Slice or one refactoring goal. Never both.
|
||||
- ❌ **No skipped tests:** Failing/skipped tests must be fixed or logged as DECISION_REQUIRED.
|
||||
- ❌ **No SELECT \*:** Always explicit columns. Dapper + schema-qualified SQL only.
|
||||
- ❌ **No direct cross-module queries:** Use approved contracts and read models only.
|
||||
- ❌ **No DateTime.Now:** Inject IClock. No random/network/system time in Policy.
|
||||
- ❌ **No partial success:** DB state must be consistent after success/failure. No "kind of failed".
|
||||
- ❌ **No policy in Job:** Jobs execute Commands, not make decisions. Decisions stay in Domain.
|
||||
- ❌ **No real customer data in code:** Never in prompt, fixture, log, trace, or test.
|
||||
|
||||
### Model Operations Specifics
|
||||
- **Model lifecycle:** Freeze → Mature → Score → Diagnose → Hypothesis → Challenger → Validate → Review → Manual Activation. No auto-learning, auto-promotion, or auto-ordering.
|
||||
- **Sell priority:** `HARD_IMPAIRMENT → PORTFOLIO_SURVIVAL → DYNAMIC_PROFIT_FLOOR → CONCENTRATION/LIQUIDITY → OPPORTUNITY_COST → REENTRY_OPTION` (immutable).
|
||||
|
||||
- **Model lifecycle:** Freeze → Mature → Score → Diagnose → Hypothesis → Challenger → Validate → Review → Manual Activation (no auto-learning, auto-promotion, auto-ordering).
|
||||
- **Sell priority (immutable):** `HARD_IMPAIRMENT → PORTFOLIO_SURVIVAL → DYNAMIC_PROFIT_FLOOR → CONCENTRATION/LIQUIDITY → OPPORTUNITY_COST → REENTRY_OPTION`.
|
||||
- **Non-value-loss sell:** Requires ReentryWatch, new CycleId/Lot, step intervals, expiry, dedup.
|
||||
- **Activation gating:** Every model activation requires ModelCard, OOS/PBO/DSR evidence, maker-checker approval, effective_at timestamp, rollback justification.
|
||||
- **Activation gating:** Requires ModelCard, OOS/PBO/DSR evidence, maker-checker approval, effective_at, rollback justification.
|
||||
|
||||
## Tools & Scripts
|
||||
|
||||
@@ -455,14 +489,57 @@ contracts/
|
||||
metrics/ # Outcome metrics schema
|
||||
```
|
||||
|
||||
## Tech Debt Management (from AGENTS.md v16.0)
|
||||
|
||||
Every suppressed rule, deferred refactor, and architectural compromise is debt. **Manage proactively:**
|
||||
|
||||
### Tech Debt Registry
|
||||
|
||||
Location: `TECH_DEBT_REGISTER.md` (to be created in PR 4)
|
||||
|
||||
Format:
|
||||
```
|
||||
| ID | Category | Impact | Effort | Status | Debt | Owner | Notes |
|
||||
|----|----------|--------|--------|--------|------|-------|-------|
|
||||
| DEBT-001 | Code Analysis (CA1822) | Medium | Low | Backlog | Static method hints | Team | Can batch with refactor |
|
||||
| DEBT-002 | Code Analysis (CA1873) | Low | Low | Backlog | Array allocation in logs | Team | Remove when performance-critical |
|
||||
```
|
||||
|
||||
**Impact/Effort Matrix:**
|
||||
- **High Impact / Low Effort:** Sprint ASAP (quick wins)
|
||||
- **High Impact / High Effort:** Roadmap (quarterly sprint)
|
||||
- **Low Impact / Low Effort:** Batch with feature work
|
||||
- **Low Impact / High Effort:** Monitor; defer unless blocking
|
||||
|
||||
### Current Debt (Provisional)
|
||||
|
||||
From `Directory.Build.props` NoWarn:
|
||||
- `CA1822` (static method hints) — Low priority, batch during refactors
|
||||
- `CA1873` (array allocation in logging) — Monitor, low impact
|
||||
- `CA1305` (culture-specific formatting) — Accept as-is for Serilog
|
||||
- `CA1707` (test naming convention) — xUnit uses underscores; accept
|
||||
- `CA1861` (static readonly arrays) — Low priority, batch
|
||||
- `xUnit2031` (Assert.Single filter) — Test analyzer; can defer
|
||||
|
||||
### Paydown Target
|
||||
|
||||
**Quarterly paydown goal:** 20% of debt list resolved (by impact, not count).
|
||||
|
||||
Track in:
|
||||
- Sprint retrospectives
|
||||
- PR descriptions (reference Debt ID when resolving)
|
||||
- README.md status section
|
||||
|
||||
---
|
||||
|
||||
## Validation Gates (Not Yet Passed)
|
||||
|
||||
Do NOT claim production readiness until:
|
||||
- `.NET 10 restore/build/test` on CI passes consistently
|
||||
- `pnpm frozen install/typecheck/Vitest/build/Playwright` on CI passes
|
||||
- PostgreSQL DbUp fresh/upgrade/re-run/failure-recovery tests pass
|
||||
- Outbox/Inbox crash-recovery & audit reconciliation rehearsal passes
|
||||
- 252+ trading-day shadow run with OOS at multiple market phases
|
||||
- PBO (probability of backtest overfit) and DSR (daily sharpe ratio) evidence
|
||||
- ✅ `.NET 10 restore/build/test` on CI passes consistently
|
||||
- ⏳ `pnpm frozen install/typecheck/Vitest/build/Playwright` on CI passes (pending PR 4)
|
||||
- ⏳ PostgreSQL DbUp fresh/upgrade/re-run/failure-recovery tests pass (pending PR 5)
|
||||
- ⏳ Outbox/Inbox crash-recovery & audit reconciliation rehearsal passes
|
||||
- ❌ 252+ trading-day shadow run with OOS at multiple market phases
|
||||
- ❌ PBO (probability of backtest overfit) and DSR (daily sharpe ratio) evidence
|
||||
|
||||
Before all gates pass: **No production deployment, no advisory-with-automation, no auto-ordering, no auto-model-promotion.**
|
||||
|
||||
Reference in New Issue
Block a user