kjh2064/QuantEngineByItz
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
codex/snapshot-admin-wbs-finalize
QuantEngineByItz/AGENTS.md
T

11 KiB
Raw Permalink Blame History

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

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, 코드, 데이터 파일 경로와 검증 명령을 함께 적는다.

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/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/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_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.
  • 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.
  • Temp/snapshot_admin_approval_packet_v1.json: snapshot admin approval packet export.
  • Temp/snapshot_admin_approval_packet_v1.md: snapshot admin approval packet summary.
  • gas_event_calendar.gs: 이벤트 캘린더 배포 호환 스텁. seedEventCalendar_() / runEventRisk() 진입점을 유지한다.
  • 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/, suggest/, artifacts/archive/: 문서 검색/색인 제외 대상. 감사나 이력 추적이 필요할 때만 명시적으로 읽는다.
  • 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)을 통한 검증을 유도 및 가이드해야 한다.

4. 보고 규칙

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

5. 개발 규칙

  • 새 기능은 contract, schema, golden case, owner ledger를 먼저 만든다.
  • 구현은 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를 유지한다.
  • 경로가 새로 생기면 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 유발
    • Synology CI는 /usr/bin/python3를 사용하므로 .gitea/workflows/ci.yml은 python3 유지

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으로 승격하지 않는다.
  • GAS는 투자 판단 로직을 새로 받아서는 안 된다 (thin adapter 원칙 — ADR-0002).
  • 프롬프트가 LLM에게 가격·수량·임계값·점수를 직접 계산하도록 요청하는 것을 금지한다.
  • 하네스 FAIL 상태를 실행 가능한 주문 표로 렌더링하지 않는다.
  • 최종 결정 권한은 단일 캐노니컬 실행 패킷(final_decision_packet_active.json)에서만 나온다.

7. Rule Index

Reference in New Issue View Git Blame Copy Permalink