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_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 표준 계약.
• 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.
• 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. Razor Pages 개발 규칙 (Tabler 참조 모델 적용)

• 핵심 아키텍처 원칙: 어드민 웹 개발은 ASP.NET Core Razor Pages 패턴 및 단일 책임 원칙(SRP)을 따르는 비즈니스 서비스 분리를 최우선 가치로 준수한다.
• 렌더 모드 표준: 순수 서버 사이드 렌더링(SSR) 및 Razor 뷰 엔진을 활용하며, UI 디자인은 Tabler CSS/JS 프레임워크 표준에 맞추어 구현한다.
• 보안 및 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 등) 및 뷰 엔진 레이아웃은 합의된 양식을 엄격히 준수하도록 표준화하고, 핵심 퀀트 리팩토링 단계마다 빌드 무결성을 보증하도록 아키텍처를 구조화한다.

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로 읽지 않는다.