From ddc68f28f5b4b7d8b2088fcbb9d3b04736d95c51 Mon Sep 17 00:00:00 2001 From: kjh2064 Date: Sun, 2 Aug 2026 05:39:06 +0900 Subject: [PATCH] docs: Add v16.0 Strategic Architecture & Engineering Excellence guidelines to AGENTS.md Add comprehensive decision framework for all work: - SOLID principles with domain context - Code refactoring (complexity, mass) - Data integrity (PIT, revision, audit) - Necessity-driven (no gold-plating) - Normalization strategy (3NF writes, denormalized reads) - Process simplification (single responsibility, clarity) - Patterns & standards (Vertical Slice, standardized components) - Guardrails (AI, traceability of decisions) - Reproducibility & history (traceability, repeatability) - Reliability (idempotency, rollback, failure modes) - Componentization & maturity (versioning, contracts-first) - Right way not shortcuts (root cause, review discipline) - Tech debt management (registry, paydown cadence) Include: - Rationale for each dimension - Application guidance - Decision checklist for all tasks - Anti-patterns (explicit blockers) This ensures every AI-assisted change, refactor, and decision follows architectural excellence criteria, not convenience. Co-Authored-By: Claude Haiku 4.5 --- AGENTS.md | 120 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index e246ab1b..e83eafbe 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -69,3 +69,123 @@ - Model operation automation stops at evaluation/proposal. Model activation is human change approval only. - J39 and every new schedule remain disabled until their source, calendar, ownership and alert contracts are approved. - Never claim .NET, pnpm, PostgreSQL, Playwright or Shadow evidence passed unless the actual artifact is attached. + +## v16.0 Strategic Architecture & Engineering Excellence + +### Decision Criteria for All Work + +Every task — code change, refactor, new feature, tooling, infrastructure — must be evaluated against these dimensions before implementation: + +#### 1. SOLID 원칙 +- **S**ingle Responsibility: One class, one reason to change. Vertical Slice boundaries are trust boundaries. +- **O**pen/Closed: Open for extension (new Policies, new decision gates); closed for modification (immutable Evidence, append-only migrations). +- **L**iskov Substitution: Handlers, Policies, Adapters are swappable; never break contract. +- **I**nterface Segregation: IClock ≠ IDateTime; IOutboxWriter ≠ IEventBus. Ports are narrow. +- **D**ependency Inversion: Depend on abstractions (IClock, ILogger, IOutboxWriter); inject concretions at composition root only. +- **적용:** 모듈 경계 설계, 인터페이스 분리, 스태틱 메서드 vs 인스턴스 메서드 판단. + +#### 2. 코드 리팩토링 (Code Mass & Complexity) +- Cyclomatic Complexity ≤ 10 per method (Policy는 예외: decision trees는 복잡해질 수 있음). +- Characterize → Isolate → Transform → Verify → Simplify → Observe → Close Debt (정공법). +- Dead code, unused flags, unreachable branches는 즉시 삭제. "혹시 필요할까봐"는 금지. +- Performance refactor와 기능 변경은 분리된 PR. 동시 변경은 회귀 탐지 불가. + +#### 3. 데이터 정합성 (Data Integrity & Audit) +- **PIT (Point-in-Time):** `WHERE published_at <= cutoff AND revision = latest` 필수. 시간 여행 쿼리는 audit 목적만. +- **Revision Tracking:** update/delete 금지. 새 버전을 append로 저장. 수정은 correction event로 보존. +- **Audit Trail:** EvidenceSnapshot, DatasetId, Model/Config/Code SHA는 Decision과 함께 저장. Trace 불가능하면 미완성. +- **적용:** 모든 쓰기는 append/correction 패턴. 읽기는 PIT 조건. 마이그레이션은 회원가입 없음. + +#### 4. 과유불급 (Necessity-Driven, No Gold-Plating) +- "혹시 나중에 필요하면"으로 코드를 추가하지 않는다. 근거 없는 추상화 금지. +- 한 곳에서만 쓰면 분리하지 않는다. 세 곳에서 반복되면 그때 abstract. +- Feature flag, backward-compat shim, deprecation layer는 근거 있을 때만. 사용하지 않는 코드는 삭제. +- **적용:** 새 service/interface/config 도입 전에 "이것이 정말 필요한가?" 자문. + +#### 5. 정규화 & 역정규화 (Normalization Strategy) +- **Write Models:** 3NF + append + revision. 중복 없음, 관계 명확, 이상 불가. +- **Read Models:** Denormalized projections. 1NF 위반 허용 (성능, 접근성). 모든 Read는 versioned, rebuildable. +- **경계:** Write는 Dapper로 스키마-규정. Read는 쿼리 최적화. 양쪽 스키마 감시. +- **적용:** 새 column 추가 전에 "이것은 3NF 위반인가? 그렇다면 projection으로." + +#### 6. 프로세스 단순화 (Simplicity & Clarity) +- 한 번에 한 가지만 한다. 다중 책임 = 다중 이해 실패 = 버그. +- "왜 이 순서인가?" 묻지 않아도 명확한 코드. 숨겨진 전제 금지. +- Circular dependency, magic numbers, implicit state 제거. +- **적용:** 코드 흐름이 위→아래로 읽혀야 함. 뒤로 돌아가며 읽어야 하면 리팩터. + +#### 7. 패턴화, 표준화, 구조화 (Patterns & Standards) +- Vertical Slice는 단일 패턴. Endpoint → Handler → Policy → Dapper → Outbox. +- Job은 단일 책임. 비즈니스 정책은 들어가지 않음. 승인된 Command만 실행. +- Event schema는 contract-first. 구독자가 없으면 이벤트도 없음. +- **표준 컴포넌트:** QueryStateBoundary, CrudForm, PermissionGuard 등은 모든 화면에서 재사용. 직접 import 금지. +- **적용:** 새 pattern/component 도입 전 팀 검토. 코드 사본 3개 = abstract 신호. + +#### 8. 바이브코딩 & 홀루시네이션 통제 (AI Guardrails) +- AI 생성 코드는 근거 없음. Source/Assumption/Decision 반드시 기록. +- **금지:** 근거 없는 Policy ID, threshold, DB column, API endpoint. +- SQL은 schema owner, PIT 조건, index, execution plan 검토 필수. +- 알고리즘 변경은 Golden/Frozen OOS diff 없이 병합 금지. +- **적용:** "이 값은 어디서 나왔나?" 묻는 습관. 답 없으면 DECISION_REQUIRED 표시. + +#### 9. 현장감, 재현성, 이력성 (Traceability & Reproducibility) +- **현장감:** Build/test/migration artifact는 보존. "통과했다고 주장"하되 증거 없으면 거짓. +- **재현성:** 동일 input → 동일 output. Random, network, system time 의존은 격리. Mock 금지, integration test로. +- **이력성:** Commit message는 "왜"를 기록. "버그 수정"은 불충분. "X 기능에서 Y 조건에서 Z 버그 → 원인: 로직 오류" 기록. +- **적용:** CI/CD 결과물 저장, 회귀 테스트 잠금, ADR에 의사결정 기록. + +#### 10. 안정성 (Reliability & Safety) +- Idempotency: 같은 요청 → 같은 결과. 두 번 실행해도 안전. +- Rollback 불가능한 변경 금지. Migration도 down script 필수. +- Failure mode: 각 Job/Endpoint은 실패했을 때 상태를 명확히. "실패했는데 부분 성공?" 금지. +- **적용:** Command/Job는 IdempotencyKey, Watermark 필수. DB constraint, NOT NULL 검증. + +#### 11. 고도화 & 컴포넌트화 (Componentization & Maturity) +- 한 번 제대로. 임시방편 금지. 기술부채는 Debt register에 기록. +- 구현 전 contract/schema/test 먼저. "하면서 배운다"는 설계 부실의 신호. +- 버전 관리: 기능이 아닌 contract 버전. API/Event/DB schema 버전 분리. +- **적용:** Release note에는 contract version, breaking change, migration step 명시. + +#### 12. 정공법 (Right Way, Not Shortcuts) +- 안 되는 길에 시간 낭비하지 말되, 편한 길도 피한다 (--no-verify, force push). +- 문제 근본 해결. Symptom 치료는 debt 증가. +- 리뷰어가 "이게 최선인가?" 묻는 코드는 재작성. "충분히 좋다" ≠ "최선". +- **적용:** Build 실패 → --no-verify X, 원인 파악. Merge conflict → cherry-pick X, rebase 제대로. + +#### 13. 기술부채 관리 (Tech Debt Registry) +- 부채는 기록하는 순간부터 이자 발생. 미루지 말 것. +- **Debt ID:** TECH-001 등으로 추적. PR/commit에서 참조. +- **우선순위:** Impact (얼마나 큰가) × Effort (고치는 데 드는 비용). 고영향 저비용 우선. +- **Paydown:** 분기마다 debt 20% 감축 목표. 신규 debt > paydown이면 질식. +- **적용:** README.md의 TECH_DEBT_REGISTER 매월 검토. 3개월 미해결 = 리팩터 스프린트 필요. + +### Work Decision Checklist + +모든 task에 대해 다음을 자문: + +- [ ] **SOLID:** 이 변경이 단일 책임인가? Dependency inversion을 지킬 것인가? +- [ ] **Complexity:** 함수/메서드 복잡도는 10 이하인가? (Policy 예외) +- [ ] **Audit:** Evidence/Revision 추적 가능한가? PIT 쿼리 있는가? +- [ ] **Necessity:** 근거 있는 변경인가? "혹시 필요하면" 아닌가? +- [ ] **Normalization:** 쓰기는 3NF, 읽기는 projection인가? +- [ ] **Simplicity:** 위→아래로 읽혀야 하는가? 숨겨진 전제 없는가? +- [ ] **Pattern:** 표준 Slice/Job/Component 따르는가? 새 패턴 도입은 검증됐는가? +- [ ] **Guardrails:** 근거 있는가? "왜"를 기록했는가? +- [ ] **Traceability:** Artifact 보존되는가? Reproduction 가능한가? ADR/Issue 링크 있는가? +- [ ] **Safety:** Idempotent인가? Rollback 가능한가? 부분 실패 케이스 처리했는가? +- [ ] **Maturity:** 임시방편 아닌가? Contract/schema/test 먼저 했는가? +- [ ] **Right Way:** Shortcut (--no-verify, force) 안 썼는가? 근본 해결했는가? +- [ ] **Debt:** 새로운 debt 만들지 않는가? 기존 debt 감축하는가? + +### Anti-Patterns (금지) + +- ❌ "일단 만들고 나중에 리팩터" → Feature 초기부터 정공법 +- ❌ "혹시 필요할까봐 추상화" → Necessity-driven만 +- ❌ SELECT * / Generic Repository → Explicit columns, explicit logic +- ❌ "이건 작은 변경이라 테스트 스킵" → 모든 경로 characterize +- ❌ Timestamp를 직접 DateTime.Now → IClock 주입 +- ❌ Policy 로직이 Job/Handler에 → Domain Policy만 +- ❌ "나중에 monitoring 추가" → 배포 전 Metric/Alert/Runbook 필수 +- ❌ Magic number → 근거 있는 상수, Policy ID로 추적 +- ❌ "다른 모듈 테이블 조회" → Contract/Read Model만 +- ❌ 스킵된 테스트 기록 안 함 → Debt register에 DECISION_REQUIRED