QuantEngineByItz/AGENTS.md

은퇴자산포트폴리오 투자 에이전트 운영 지침

QuantEngine 운영 설정 권위

• ConnectionStrings__DefaultConnection은 운영 설정에서 관리한다.
• 저장소 코드, DbUp migration, CI artifact는 운영 계정 비밀번호를 생성하거나 덮어쓰지 않는다. 단, 명시된 운영 설정 복원 작업은 예외로 한다.
• 배포/검증 하네스는 설정값을 읽기만 하며, 값 자체를 로그·증빙·커밋에 기록하지 않는다.
• 설정 변경은 애플리케이션 배포와 분리된 운영 설정 변경으로 취급한다. 설정 복원 시에는 Git 이력의 마지막 권위값만 사용한다.

0. 최우선 원칙

• 이 파일은 운영 인덱스다. 상세 규칙은 governance/rules/*.yaml와 spec/*.yaml를 우선한다.
• 가격, 수량, TP/SL, 점수는 오직 spec/13_formula_registry.yaml와 하네스 산출값만 사용한다.
• 임의 계산, 임의 가격, 임의 수량, 미등록 공식은 금지한다.
• 하네스 결측은 DATA_MISSING — 하네스 업데이트 필요로만 표시한다.
• 차단된 종목의 산출값은 숨기지 말고 shadow ledger로 투명하게 남긴다.

0b. 기본 하네스 완료 조건

• 모든 작업은 YAML + 코드 + 데이터 실체 + 검증 증빙이 모두 존재할 때만 완료로 본다.
• YAML은 계약/공식/거버넌스의 원본 권위다. 관련 spec 또는 governance 파일이 함께 갱신되어야 한다.
• 코드는 src/ 또는 tools/의 canonical 구현과 생성물이 함께 맞아야 한다.
• 데이터 실체는 Temp/, GatherTradingData.xlsx, GatherTradingData.json, runtime/ 등 실제 산출물 또는 데이터 파일로 확인되어야 한다.
• 검증 증빙은 재현 가능한 명령 출력 또는 생성된 검증 결과 파일로 남겨야 한다.
• 위 4가지 중 하나라도 빠지면 작업은 미완료다. 요약이나 설명만으로 완료 처리하지 않는다.
• 완료 보고에는 반드시 변경된 YAML, 코드, 데이터 파일 경로와 검증 명령을 함께 적는다.

0c. 작업 수행 절차 강제

• 모든 작업은 아래 순서를 반드시 따른다.
  1. 로드맵/현황 확인
  2. WBS 작성
  3. 목표 설정
  4. 성공판단 데이터 정의
  5. 구현
  6. 사후 검증
  7. 증빙 기록
• 작업 시작 전에는 반드시 해당 작업의 WBS 항목과 성공판단 데이터를 문장 또는 표로 먼저 확정한다.
• 성공판단 데이터가 없으면 구현을 시작하지 않는다.
• “한 줄 추가”, “작아 보이는 수정”도 예외가 아니다. 모든 변경은 WBS와 성공판단 데이터에 매핑되어야 한다.
• 작업 도중 범위가 바뀌면 WBS를 먼저 갱신하고 난 뒤에만 구현을 계속한다.
• 작업 완료 판정은 구현 완료가 아니라 검증 통과와 증빙 기록까지 확인된 경우에만 가능하다.
• 사후 검증 없이 “대충 괜찮다” 식의 진행은 금지한다.

1. 읽는 순서

1. runtime/active_artifact_manifest.yaml
2. Temp/final_decision_packet_active.json (manifest alias)

1b. Critical Authority Files

• spec/00_execution_contract.yaml
• spec/risk/aggregate_risk.yaml
• spec/risk/portfolio_exposure.yaml
• spec/14_raw_workbook_mapping.yaml
• spec/15_account_snapshot_contract.yaml
• spec/02_data_contract.yaml
• spec/09_decision_flow.yaml
• spec/12_field_dictionary.yaml
• spec/13_formula_registry.yaml

2. 문서 역할

• AGENTS.md: 운영 헌법과 링크 인덱스.
• governance/agents_index.yaml: rule file 목록과 hash migration index.
• governance/rules/*.yaml: 장문의 세부 규칙.
• spec/*.yaml: 계약, 공식, 게이트, 출력 계약의 원본 권위.
• src/quant_engine: canonical Python package. schema/model parity와 reporting helper를 담는다.
• tools/*.py: 검증/생성 CLI. 가능한 한 얇게 유지한다.
• Temp/*.json: 런타임 산출물. 읽기 전용 취급이며 직접 편집하지 않는다.
• schemas/*.schema.json: shape validation.

2b. Directory Routing / Serving

• spec/: source of truth. 공식, 계약, 게이트, 출력 스키마의 최우선 읽기 경로.
• governance/: 운영 규칙, 인덱스, 해시 마이그레이션, ADR, 템플릿.
• src/: Python canonical implementation. 새 로직은 여기부터 반영한다.
• src/dotnet/QuantEngine.Tools: canonical .NET operational report and packet renderer.
• src/quant_engine/data_collection_backend_v1.py: collection backend selector.
• src/quant_engine/data_collection_store_v1.py: SQLite collection store.
• src/quant_engine/kis_data_collection_v1.py: KIS 우선 수집기.
• src/quant_engine/kis_data_collection.db: canonical KIS collection SQLite read surface.
• src/quant_engine/snapshot_admin.db: canonical snapshot admin workspace SQLite read/write surface.
• src/quant_engine/storage_backend_v1.py: storage backend contract.
• KIS-first: KIS 우선.
• SQLite-first: SQLite/JSON 우선.
• tools/: build/validate/convert/audit CLI.
• tools/render_operational_report.py: legacy renderer, 운영/CI 경로에서 사용 금지.
• tools/run_kis_data_collection_v1.py: KIS collection thin CLI.
• tools/generate_postgresql_upgrade_stub_v1.py: PostgreSQL stub generator.
• tools/validate_platform_transition_wbs_v1.py: .gs → Python and xlsx → sqlite WBS validator.
• tools/validate_qualitative_sell_strategy_pipeline_v1.py: qualitative sell validator.
• tools/validate_gitea_secrets_contract_v1.py: Gitea secrets validator.
• tools/validate_gitea_ci_workflow_lint_v1.py: CI workflow lint validator for recurring service-binding mistakes.
• tools/validate_gitea_pr_harness_v1.py: Gitea PR 생성/조회 하네스.
• tools/validate_gitea_token_home_v1.py: Gitea 토큰 유효성 검증용 하네스.
• tools/gitea/: Gitea API 하네스 패키지 (단일 권위). 토큰 우선순위: GITEA_TOKEN_BAIK → GITEA_TOKEN_TAXBAIK → GITEA_TOKEN → GITEA_TOKEN_HOME.
  • tools/gitea/client.py: GiteaClient - SOLID SRP 기반 Gitea REST API v1 클라이언트 (runs/jobs/secrets/vars/runners/PR/releases 지원).
  • tools/gitea/harness.py: CLI 하네스 진입점. python tools/gitea/harness.py health|runs|run <id>|secrets|vars|workflows|runners|dispatch <yml> 형식으로 사용.
  • tools/inspect_gitea_actions_run_v1.py / v2.py: 구 하네스 (레거시, tools/gitea/harness.py run <id>으로 대체).
• tools/validate_snapshot_admin_web_v1.py: snapshot admin smoke validator.
• tests/parity/test_price_qty_parity_v1.py: price/qty parity.
• tests/parity/test_score_parity_v1.py: timing score parity.
• tests/parity/test_routing_gate_parity_v1.py: routing gate parity.
• .gitea/workflows/qualitative_sell_strategy.yml: qualitative sell strategy workflow.
• .gitea/workflows/snapshot_admin.yml: snapshot admin workflow and scheduled validation.
• .gitea/workflows/ci_lint.yml: CI workflow lint gate for .gitea/workflows/ci.yml.
• docs/CLOUD_SERVER_SETUP.md: 클라우드 서버(hz-prod-01, 178.104.200.7) 설정 하네스 가이드. 시놀로지 → 클라우드 마이그레이션 매핑 포함.
• docs/GITEA_SECRETS_SETUP.md: Gitea secrets setup and verification guide.
• docs/GATHERTRADINGDATA_XLSX_OPERATING_RUNBOOK.md: GatherTradingData.xlsx 보조 자산 런북.
• docs/ROADMAP_WBS.md: .gs → Python 및 xlsx → sqlite WBS.
• docs/ROADMAP_WBS.md의 WBS-8.2: run_kis_data_collection_v1.py → validate_platform_transition_wbs_v1.py → validate_snapshot_admin_web_v1.py.
• docs/WBS_10_DOTNET_MIGRATION_ROADMAP.yaml: .NET 엔진 고도화 상세 WBS와 각 WBS별 성공 데이터 가이드.
• docs/WBS_10_DOTNET_MIGRATION_INVENTORY.yaml: WBS-10 전환 우선순위용 실행 경로 인벤토리.
• docs/WBS_10_DOTNET_MIGRATION_EXECUTION_PLAN.yaml: WBS-10 착수용 실행 분해 계획.
• docs/WBS_10_DOTNET_PARITY_CONTRACT.yaml: WBS-10 핵심 계산기 parity 계약.
• docs/WBS_10_DOTNET_PROVENANCE_CONTRACT.yaml: WBS-10 provenance payload 표준 계약.
• docs/WBS_10_DOTNET_SCHEDULER_CONTRACT.yaml: WBS-10 scheduler state machine 계약.
• docs/WBS_10_DOTNET_NORMALIZATION_CONTRACT.yaml: WBS-10 normalization/read model 계약.
• docs/WBS_10_DOTNET_IDEMPOTENCY_CONTRACT.yaml: WBS-10 idempotency/lock 계약.
• docs/WBS_10_DOTNET_CICD_CHAIN_CONTRACT.yaml: WBS-10 CI/CD 순차 게이트 계약.
• docs/WBS_10_DOTNET_DOMAIN_PARITY_BACKLOG.yaml: WBS-10 domain parity backlog contract.
• docs/WBS_10_DOTNET_READ_MODEL_CONTRACT.yaml: WBS-10 read model contract.
• tools/validate_dotnet_migration_roadmap_v1.py: WBS-10 상세 로드맵 YAML validator.
• tools/validate_dotnet_migration_execution_plan_v1.py: WBS-10 실행 분해 계획 validator.
• tools/validate_dotnet_parity_contract_v1.py: WBS-10 parity 계약 validator.
• tools/validate_dotnet_provenance_contract_v1.py: WBS-10 provenance 계약 validator.
• tools/validate_dotnet_scheduler_contract_v1.py: WBS-10 scheduler 계약 validator.
• tools/validate_dotnet_normalization_contract_v1.py: WBS-10 normalization 계약 validator.
• tools/validate_dotnet_idempotency_contract_v1.py: WBS-10 idempotency 계약 validator.
• tools/validate_dotnet_cicd_chain_contract_v1.py: WBS-10 CI/CD chain 계약 validator.
• tools/validate_dotnet_domain_parity_backlog_v1.py: WBS-10 domain parity backlog validator.
• tools/validate_dotnet_domain_parity_artifact_v1.py: WBS-10 domain parity artifact validator.
• tools/validate_dotnet_read_model_contract_v1.py: WBS-10 read model validator.
• Temp/snapshot_admin_approval_packet_v1.json: snapshot admin approval packet export.
• Temp/snapshot_admin_approval_packet_v1.md: snapshot admin approval packet summary.
• Temp/: 실행 결과와 캐시. 라우팅 대상은 아니며 runtime consumer만 읽는다.
• DB 파일 관리: workspace/collector DB는 단일 canonical 경로만 사용한다. 동일 역할의 SQLite 파일을 src/와 outputs/에 중복 생성하지 말고, 실행 기본값·README·WBS·검증 스크립트가 같은 경로를 가리키게 유지한다. 임시 검증 DB는 Temp/에만 두고, 운영 기준 DB로 승격할 때는 명시적으로 문서화한다. canonical workspace DB는 src/quant_engine/snapshot_admin.db이며, 다른 위치의 동일 역할 DB는 파생/아카이브/마이그레이션 전용으로만 취급한다. 운영 진입점과 일반 검증 스크립트는 canonical 파일만 읽고 써야 한다.
• docs/archive/, docs/legacy/, suggest/, artifacts/archive/, src/quant_engine/deprecated/: 문서 및 폐기된 파이썬 코드 검색/색인 제외 대상. 감사나 이력 추적이 필요할 때만 명시적으로 읽는다.
• dist/, artifacts/, docs/, examples/, prompts/, schemas/, tests/: 패키징/문서/검증/산출물 보조 경로.
• run_all: 외부 스케줄러가 호출하는 진입점으로 유지한다. 실행 시 run_all_invocation_mode=external_scheduler를 기준으로 해석한다.

3. 하드 룰

• 가격 임의 창작 금지.
• 다중 조건 접속사 기반 주문문 금지 (모든 매도는 단일 sell priority table 및 waterfall 방식으로 선형 처리).
• tick normalization 의무.
• TP stale 값은 제거.
• sell candidate가 2개 이상이면 sell priority table을 먼저 출력.
• LLM은 하네스 판정을 번복하지 않으며, 임의로 사칙연산, 평균, 순위(rank) 등을 재계산하지 않고 context key를 그대로 copy-only하여 렌더링한다.
• 외부 시장 데이터는 참고용이며 JSON harness가 우선한다.
• provenance 없는 숫자는 보고서에 쓰지 않는다.
• 추격 매수 방지를 위해 모든 매수 진입은 anti-late entry gate 검증을 필수로 통과한다.
• 데이터 흐름은 단방향(Data -> Feature -> Decision -> Execution -> Report) 아키텍처 경계를 유지하며, renderer가 core 계산을 호출하는 역참조를 금지한다.
• D+2 영업일 기준 현금을 즉시방어 자산으로 간주하고, 목표 예산 5억 원을 기준으로 포지션 사이징 및 리스크 버킷을 제어한다.
• 매주 주말 리밸런싱(rebalance_required=true) 및 매월 1일/11일/21일 중간점검(mid_check_required=true) 운영 cadence를 준수한다.
• 커밋, 푸쉬, PR 작업 시 반드시 로컬의 .gs 파일을 Google Apps Script 원격 프로젝트에 업로드(python tools/deploy_gas.py 실행)하고, 사용자에게 스프레드시트 상의 스크립트 실행(예: runDataFeed)을 통한 검증을 유도 및 가이드해야 한다.
• QuantEngine 배포는 CI 전용이다. 로컬에서 서버로 산출물을 직접 업로드하거나 scp/rsync로 수동 반영하지 않는다. 실배포는 .gitea/workflows/deploy-prod.yml만 사용하며, 로컬 스크립트는 CI 환경에서만 실행 가능해야 한다.
• 원격 서버 확인이 필요하면 ssh kjh2064@178.104.200.7 접속을 먼저 시도하고, 사용자에게 매번 접속 확인을 요구하지 말고 직접 상태/로그/헬스체크를 수집한 뒤 결과만 보고한다.

4. 보고 규칙

• 모든 숫자에는 반드시 provenance(출처)를 남기며, 출처가 유효하지 않거나 없는 숫자는 보고서 표기를 전면 배제(DATA_MISSING 처리)한다.
• 보고서 첫 부분에는 portfolio health와 주요 차단 사유를 먼저 쓴다.
• blocked/limited 상태라도 산출된 기준가, 손절가, 익절가, 수량은 숨기지 않는다.
• narrative는 숫자와 게이트를 완화하는 표현을 쓰지 않는다.

5. 개발 규칙

• 새 기능은 contract, schema, golden case, owner ledger를 먼저 만든다.
• 그 다음에 WBS와 성공판단 데이터(테스트/검증 입력과 기대값)를 먼저 만든다.
• 구현은 Python canonical first, GAS adapter second다.
• tools/*.py는 CLI wrapper에 가깝게 유지한다.
• gas_*.gs는 thin adapter 방향으로 유지한다.
• src/quant_engine는 canonical package로 유지한다.
• schemas/generated와 src/quant_engine/models/generated는 schema/model parity를 유지한다.
• 코드 변경은 WBS 항목 번호와 성공판단 데이터 파일/명령을 함께 남겨야 한다.
• 검증 결과가 없으면 완료 보고를 하지 않는다.
• 경로가 새로 생기면 AGENTS.md의 Directory Routing / Serving 섹션과 zip 화이트리스트를 함께 갱신한다.
• Python 인터프리터: Windows 로컬 환경에서는 반드시 python을 사용한다 (python3 금지).
  • python → Python 3.13.5 (Python313/) — yaml/openpyxl/yfinance 등 프로젝트 패키지 설치됨
  • python3 → Python 3.12 (Windows Store) — 프로젝트 패키지 미설치 → ModuleNotFoundError 유발
  • 클라우드 서버(hz-prod-01)는 /usr/bin/python3를 사용하므로 .gitea/workflows/ci.yml은 python3 유지
• 임시 파일 관리: 개발/디버깅 목적의 모든 휘발성 임시 파일 및 로그는 반드시 Temp/ 디렉토리 하위에서만 생성해야 하며, 루트나 다른 패키지 경로에 임시 파일을 만드는 것은 금지한다. 불가피하게 생성할 경우 반드시 접두사/접미사 규칙(debug_*, tmp_*, mock_*, *_temp.*)을 준수하여 .gitignore에 필터링되도록 한다.

5b. Vue 3 + Vite 프론트엔드 개발 규칙 (표준 기술 스택 적용)

• 핵심 아키텍처 원칙: 어드민 웹 및 클라이언트 프론트엔드는 Section 5e의 표준 기술 스택 명세에 따라 Vue 3 / Vite 8 / Single File Component (.vue) 아키텍처를 고수한다. (기존 Razor Pages SSR 단독 고정 규칙은 폐기됨)
• 컴포넌트 & 데이터 그리드 표준: UI 컴포넌트 및 데이터 그리드는 PrimeVue 및 AG Grid 표준 컴포넌트를 활용하며, 상태 관리는 Pinia, 데이터 페칭은 **TanStack Query (Vue Query)**를 적용한다.
• 보안 및 CSRF 방어: 모든 POST/CUD 액션 처리 시 안티포저리 토큰(@Html.AntiForgeryToken()) 유효성 검증을 필수로 수행하여 CSRF 공격을 전면 차단한다.
• UI/UX 구현:
  • Tabler 기반 테이블 뷰와 모달 대화상자(Modal Dialog) 패턴을 일관되게 활용하여 CRUD 및 데이터 수정 저장을 플래시 없이 유연하게 연동한다.
  • 상태 및 등급 구분에는 시각적 가시성을 위한 Status Color Chips(Success, Warning, Error)를 적용한다.
• 엔지니어링 표준화 지침:
  • 표준화 & 컴포넌트화: 공통 레이아웃(_AdminLayout.cshtml)과 부분 뷰(Partial View)를 적극적으로 분리/재사용하고, 파편화된 개별 스타일을 지양하여 Tabler 및 표준 유틸리티 클래스를 공통 활용한다.
  • 데이터 정합성 & 리팩토링: 모든 비즈니스 도메인의 상태 전이는 ACID 트랜잭션 단위 및 인프라 레이어의 일관성 제어 규칙을 보장하며, 복잡도가 과한 하드코딩 영역은 SRP(단일 책임 원칙) 및 인터페이스 기반 구조로 점진적 리팩토링한다.
  • 파편화 & 바이브 코드 방지: provenance(근거) 없는 암묵적 룰이나 감에 의존한 구조(Vibe Code)의 무분별한 탑재를 금지하고, 모든 상태 및 에러 코드는 코드북에 엄격히 등록된 정방형 정규 값만 할당한다.
  • 하네스 & 테스트 안정성: 모든 패치는 Temp/ 및 하네스 테스트 스위트의 빌드 및 통과 로그를 통해 데이터로 증빙한다. 하네스 실패 시 빌드 승격을 전면 차단한다.
  • 비즈니스 로직 단순화: 다차원 중첩 조건이나 연쇄 트리거를 제거하고 선형 구조(Waterfall, Sequence)의 단순 프로세스 플로우로 구현하여 추적 가능성을 극대화한다.
• 코드 및 다국어 규칙: 모든 관리자 UI 레이블, 폼, 오류 메시지는 한국어로 작성하며, 소스 코드 주석 및 내부 예외 메시지는 영어 작성을 허용한다. 클래스, 메서드, 프로퍼티는 PascalCase를 사용하고 비동기 메서드에는 Async 접미사를 지정한다.

5c. 퀀트 엔진 엔지니어링 철학 및 구현 원칙 (Operational Philosophy)

• SOLID & 컴포넌트화(Componentization) & 정공법: 모든 C#/.NET 코드 작성 시 SOLID 원칙을 준수한다. 각 모듈은 단일 책임 원칙(SRP)을 가지며, 인터페이스와 비즈니스 서비스 레이어로 철저히 컴포넌트화하여 결합도를 낮추는 정공법 아키텍처를 고수한다.
• 데이터 정합성 & 정규화/역정규화: 데이터 모델링 시 정합성 유지를 위해 관계형 데이터베이스의 정규화를 최우선으로 하며, 성능 최적화가 필수적인 어드민 조회 그리드용 데이터 전달(BFF/DTO) 시에만 제한적으로 안전하게 역정규화된 뷰 모델을 허용한다.
• 과유불급 & 프로세스 단순화: 복잡한 중첩 트리거와 과도한 추상화(Over-engineering)를 경계하는 과유불급 원칙을 따른다. 비즈니스 흐름은 최대한 선형적이고 명시적인 프로세스로 단순화하여 디버깅 및 추적 가시성을 극대화한다.
• 바이브코딩(Vibe Coding) & 할루시네이션(Hallucination) 방지: 퀀트 엔진 개발 시 LLM이나 인간 개발자의 주관적인 감(Vibe)과 추측에 의존한 임의의 상수 지정 또는 팩터 수식 재구성을 엄격히 금지한다. 모든 공식 및 의사결정 규칙은 spec/*.yaml 명세에 따라 철저히 **데이터 기반(Data-Driven)**으로 유도하고 테스트 코드로 실증한다.
• 단순 추측이 아닌 데이터 기반 예측: 퀀트 모델의 모든 예측(알파, 리스크, 목표 가격 등)은 개발자의 직관이나 단순 추측이 아닌, 과거 시계열 통계 데이터 및 재현 가능한 백필 데이터를 근거로 설계한다. 모델 성능 평가는 E2E 테스트 하네스에서 산출된 정합성 결과와 백테스팅 실증 로그 등 철저히 데이터에 기반하여 의사결정을 수행한다.
• 최적 알고리즘 & 게임이론: 슬리피지 최소화 및 레짐(시장국면) 적응형 포지션 사이징 처리 시, 호가 갭 스프레드 분석과 동적 캘리브레이션을 포함하는 최적 알고리즘을 활용하며, 시장 참여자 간의 호가 유동성 경쟁 속에서 불리한 주문이 실행되지 않도록 체결 우선순위 Waterfall 모델(게임이론적 리스크 가드)을 장착한다.
• 현장감 & 기술 부채: 빌드 경고 및 사용되지 않는 쓰레기 코드를 즉각적으로 해결하여 기술 부채의 누적을 원천 차단한다. 실제 OpenAPI 응답 레이턴시, 스레드 병목 현상 및 어드민 DB 현황 조회 시 발생하는 트래픽을 로컬 및 E2E 실증 데이터로 직접 모니터링하여 현장감 있는 실전 최적화를 구현한다.
• 패턴화 & 표준화 & 구조화: 명명 규칙, 디자인 패턴(예: Repository, Factory 등) 및 뷰 엔진 레이아웃은 합의된 양식을 엄격히 준수하도록 표준화하고, 핵심 퀀트 리팩토링 단계마다 빌드 무결성을 보증하도록 아키텍처를 구조화한다.

5d. 실무 운영 분석 및 수행 표준 지침 (Operational Execution & Analysis Harness Guidelines)

• 사전 정의 의무: 모든 작업 분석 및 수행 시 목적, 입력, 출력, 제약조건, 성공 기준을 최우선으로 정의하고, 확인된 사실, 가정, 미확인 사항을 구체적으로 분리하여 제시한다.
• 우선순위 가치: 정확성, 데이터 정합성, 단순성, 안정성, 유지보수성을 최우선으로 하되 과도한 추상화와 불필요한 고도화(Over-engineering)는 피한다.
• 위험도 및 효과 기반 4단계 작업 분류:
  1. 즉시 수정
  2. 우선 개선
  3. 단계적 개선
  4. 현재는 보류
• 구속력 있는 답변 및 보고서 7단계 작성 양식:
  1. 현재 상태와 핵심 문제 (결론 및 핵심 판단 우선 제시)
  2. 핵심 판단과 우선순위
  3. 권장 접근법
  4. 구체적인 변경 내용 (전체 코드 대신 변경 지점과 이유 중심 서술)
  5. 데이터 정합성 및 안정성 검토
  6. 테스트와 재현 절차 (실제 검증하지 않은 결과의 성공 단정 엄금)
  7. 위험, 롤백, 남은 기술부채

5e. 표준 기본 기술 스택 명세 (Standard Technology Stack Specification)

모든 시스템 설계, 리팩토링, 모듈 추가 및 프론트/백엔드 개발 시 아래 표준 기술 스택을 최우선 구속력으로 준수한다:

• Core Architecture & Runtime: .NET 10 / ASP.NET Core 10
• Architecture Pattern: Modular Monolith / Vertical Slice Architecture
• API Framework & Routing: FastEndpoints / Swashbuckle.AspNetCore (Swagger/OpenAPI)
• Database & Data Access: PostgreSQL / Npgsql / Dapper
• Migration & Schema Management: DbUp (서비스 기동 영향 완전 격리)
• Task Scheduler & Background Jobs: Hangfire
• Real-time Communication: SignalR
• Reliable Messaging & Event Consistency: Outbox + Inbox Pattern
• Frontend Stack & Build Tool: Vue 3 / Vite 8 / pnpm
• State Management & Data Fetching: TanStack Query (Vue Query) / Pinia
• Form Validation & Schema: vee-validate / Zod
• UI Components & Data Grid: PrimeVue / AG Grid (또는 Tabler SSR 참조 모델)
• Testing & E2E Framework: xUnit (.NET) / Vitest (Frontend) / Playwright (E2E)
• CI/CD Automation Pipeline: Gitea Actions
• Logging, Telemetry & Alerts: Serilog / OpenTelemetry / Telegram Notification
• HTTP Client: axios
• Routing: vue-router
• Security & Resiliency: BCrypt.Net-Next / Polly (Fault Handling)

5f. 더존 회계시스템 기준 UX/AX 디자인 & 인터랙션 표준 명세 (Douzone ERP Accounting UX/AX Standard Specification)

어드민 웹 UI/UX 및 AX(AI Experience) 설계 시 더존 회계시스템(Smart A / Amaranth 10)의 전문성과 실무 직관성을 최우선 표준으로 적용한다:

• 키보드 중심 초고속 입력 (Keyboard-Centric Interaction):
  • Enter 키로 다음 입력 필드 이동(Focus Traversal), Tab / Shift+Tab 행 간 이동, F2 조회를 일관되게 지원하여 마우스 없이 키보드만으로 거래/설정 입력이 완결되도록 한다.
  • Grid 내에서는 Arrow Keys (상하좌우 셀 이동) 및 Esc 입력 취소를 제공한다.
• 마우스 & 핫키 상호보완 (Mouse & Hotkey Synergy):
  • 마우스 클릭 시 행(Row) 전체 즉시 선택 및 우클릭 맥락 메뉴(Context Menu) 지원.
  • 마우스 휠 스크롤 시 대용량 데이터 그리드의 Virtual Scroll(무한 스크롤) 적용.
• 화면 배치 및 레이아웃 구조 (Layout Architecture):
  • 3단 분할 레이아웃 표준: 상단 검색조건 헤더 바 + 중앙 메인 데이터 그리드 (Grid) + 하단 상세/전표 summary & 핫키 안내 바.
  • 좌측 상단에는 핵심 필터, 우측 상단에는 조회(F3), 저장(F4), 삭제(F5), 엑셀다운(F7) 표준 버튼 배치.
• 컴포넌트 & 템플릿 표준 (Component & Template Standard):
  • Data Grid: AG Grid / PrimeVue Grid 기반의 고밀도(High-Density) 그리드 사용 (열 넓이 자동 조절, 컬럼 고정, 합계/수량 Footer Row 필수 제공).
  • Modal & Lookup: Code Lookup 모달 대화상자 적용 (검색 키워드 입력 즉시 자동 필터링).
• 색상 및 시각 정책 (Color & Visual Policy):
  • 눈의 피로도 최소화 채도: 더존 트레이드마크인 Soft Navy/Slate Gray (#2C3E50, #34495E) 메인 테마 적용.
  • 상태 구분 Chips 정책:
    • Success / 옥색: 정상, 승인, PASS (#2ECC71, #1ABC9C)
    • Warning / 앰버: 경고, 검토, LIMIT (#F39C12)
    • Error / 다크레드: 차단, 오류, FAIL (#E74C3C)
  • 입력 필드 상태: Focus 시 Blue Border Highlight, 읽기 전용(Disabled/Read-Only) 시 Light Gray Background (#ECF0F1).

5g. 더존 회계시스템 기준 6대 표준 화면 타입 및 입력 컴포넌트 템플릿 정책 (Douzone Standard Screen Types & Input Template Policy)

화면 구현 시 임의의 레이아웃 작성을 전면 금지하며, 아래 6대 표준 화면 타입과 컴포넌트 마스크 정책만 사용하도록 구속한다:

• 6대 표준 화면 타입:
  1. Type 1: 단일 그리드 전표형 (Single Grid View): 대용량 데이터 조회/관리 전용 (상단 검색 + AG Grid + 하단 안내 바).
  2. Type 2: Master-Detail 2단 스플릿형 (Master-Detail Split View): 30% 좌측 목록 그리드 : 70% 우측 세부 입력 폼.
  3. Type 3: 좌우 5:5 대칭 분할형 (5:5 Split View): 원천 vs 파생 데이터 대조 및 괴리율 분석 전용.
  4. Type 4: 고밀도 다층 폼 입력형 (High-Density Form View): 2열/3열 고밀도 테이블 입력 폼.
  5. Type 5: 팝업 룩업 대화상자형 (Code Lookup Modal): F2 종목/팩터 룩업 모달 (키워드 자동 필터링 + Enter 선택).
  6. Type 6: 종합 대시보드 KPI형 (Executive Dashboard): 펀드 자산 Status Chips + 4분할 차트 Widget.
• 고밀도 컴포넌트 & 입력 마스크 규격:
  • Label (라벨): width: 120px; font-weight: 700; color: #2C3E50; 우측 정렬; 필수 항목 * 표시.
  • Text Input: Focus 시 Blue Highlight (#2980B9), Enter 키로 다음 필드 포커스 자동 이동.
  • Combo / Select: Alt + Down 드롭다운 펼치기, Enter 키 선택 확정.
  • Number / Currency (마스크): Right Align, 천단위 콤마 자동 서식 (1,000,000), 음수 다크레드, 문자 입력 차단.
  • Date Input (마스크): YYYY-MM-DD 마스크 (2026-07-22), 숫자 8자리 입력 시 자동 하이픈 생성 (20260722 ➔ 2026-07-22).
  • Code Lookup: F2 돋보기 버튼 결합 룩업 모달 자동 구동.
• 동적 스플릿 바(Resizable Splitter Bar) 분할 원칙:
  • DataComparisonView.vue(Type 3) 및 DatabaseView.vue(Type 2) 등 좌/우, 상/하로 분할되는 모든 화면은 고정 크기가 아닌 **동적 스플릿 바(Resizable Splitter Bar)**를 기본 탑재하여 사용자가 마우스 드래그로 분할 비율(5:5, 3:7, 7:3 등)을 자유롭게 조절하도록 구속한다.
• 과도한 상하 스크롤 배제 및 단일 화면(1-Viewport Grid/Tab) 정책:
  • 화면 전체를 상하 수직 박스로 길게 늘어뜨려 과도한 상하 스크롤을 유발하는 레이아웃 구성은 실무 가독성 저해로 절대 금지한다.
  • 모든 메인 뷰는 단일 화면(1-Viewport) 안에서 완결되도록 설계하며, 추가 정보는 상하 스크롤이 아닌 **상단 탭(Tab) 전환**을 통해 한눈에 파악할 수 있도록 직관적 뷰를 구성한다.

6. 검증 규칙

• python tools/validate_specs.py
• python tools/validate_golden_coverage_100.py
• python tools/validate_calibration_registry_v1.py
• python tools/validate_schema_model_generation_v1.py
• python tools/validate_gas_thin_adapter_v1.py
• python tools/validate_agents_shrink_v1.py
• python tools/validate_completion_harness_instructions_v1.py

6b. 추가 운영 헌법 원칙 (proposed_AGENTS_constitution_v1 반영)

• Live T+20 표본이 30건 미만이면 active 또는 PASS_100으로 승격하지 않는다.
• 프롬프트가 LLM에게 가격·수량·임계값·점수를 직접 계산하도록 요청하는 것을 금지한다.
• 하네스 FAIL 상태를 실행 가능한 주문 표로 렌더링하지 않는다.
• 최종 결정 권한은 단일 캐노니컬 실행 패킷(final_decision_packet_active.json)에서만 나온다.

7. Rule Index

• governance/agents_index.yaml

• governance/rules/00_core_locks.yaml

• governance/rules/01_harness_contract.yaml

• governance/rules/02_portfolio_policy.yaml

• governance/rules/03_order_grammar.yaml

• governance/rules/04_reporting_contract.yaml

• governance/rules/05_migration_hashes.yaml

• 모든 수치 provenance 및 아키텍처 경계는 spec/49_refactor_methodology_contract.yaml 및 ADR-0011을 준수한다.

• 가격/수량/공식을 LLM이 즉석 정의하지 않는다.

• replay 표본을 live 운영성과로 혼입하지 않는다.

• validation 실패를 무시하지 않는다.

• deprecated artifact를 runtime source로 읽지 않는다.