From 83bda8a69f3f9bf0a21a46372cb78c36dacb8930 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Sun, 8 Feb 2026 23:56:37 +0000 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20MESA=20=ED=94=84=EB=A1=9C=EC=A0=9D?= =?UTF-8?q?=ED=8A=B8=20Constitution=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit MESA 프로젝트의 핵심 개발 원칙을 정의하는 Constitution.md를 추가합니다. 주요 원칙: - 모듈 분리 (비즈니스 로직/협업 툴/문서) - 제로 시크릿 정책 - 핵심 로직 테스트 필수 - PR 리뷰 필수 - 한국어 우선 정책 - 명시적 타입 및 Google 스타일 가이드 준수 - 방어적 프로그래밍 Resolves #29 Co-authored-by: sin seongsik --- CONSTITUTION.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 CONSTITUTION.md diff --git a/CONSTITUTION.md b/CONSTITUTION.md new file mode 100644 index 0000000..5e3caab --- /dev/null +++ b/CONSTITUTION.md @@ -0,0 +1,62 @@ +# MESA Constitution + +## Core Principles + +### I. 모듈 분리 +프로젝트는 세 개의 독립 영역으로 분리한다: +- **비즈니스 로직** (`src/`): 트레이딩 전략, 백테스팅 엔진, 거래소 연동 등 핵심 도메인 코드 +- **협업 툴** (`discord-github-worker/` 등): 봇, 자동화, 인프라 코드 +- **문서/명세** (`specs/`, `docs/`): 명세서, 설계 문서, 가이드 + +각 영역은 독립적으로 개발/배포/테스트할 수 있어야 한다. 한 영역의 변경이 다른 영역에 영향을 주면 안 된다. + +### II. 제로 시크릿 +API 키, 토큰, 비밀번호, 개인 자격증명은 **절대** 커밋하지 않는다: +- 모든 시크릿은 `.env` 파일 또는 플랫폼별 시크릿 관리 도구에 저장 +- `.gitignore`에 `.env`, `config.json`, `*.pem` 등 시크릿 파일 MUST 포함 +- PR 리뷰 시 시크릿 유출 여부를 반드시 확인 +- 실수로 커밋된 시크릿은 즉시 교체(revoke)하고 히스토리에서 제거 + +### III. 테스트 필수 (Core Logic) +돈을 다루는 핵심 로직은 반드시 검증되어야 한다: +- **Core Logic:** 트레이딩 전략, 주문 실행, 백테스팅 계산 로직은 **단위 테스트(Unit Test) 작성이 필수(MUST)**이다. +- **Verification:** 백테스팅 결과 검증은 전략 변경 시 반드시 수행한다. +- **Optional:** 단순 유틸리티, UI, 일회성 스크립트는 테스트 권장 사항(SHOULD)이다. +- 프레임워크: `pytest` 사용 + +### IV. PR 리뷰 필수 +모든 Pull Request는 최소 1명의 리뷰어 승인 후 머지한다: +- `main` 브랜치 직접 push 금지 +- 리뷰어는 코드 품질, 시크릿 유출, 원칙 준수 여부를 확인 +- AI 코드 리뷰(Claude, Copilot)는 보조 수단이며 사람 리뷰를 대체하지 않음 + +### V. 한국어 우선 +문서, 주석, 커밋 메시지는 한국어를 기본으로 한다: +- 명세서(`specs/`), README, 가이드 문서는 한국어 작성 +- **Docstring:** Google Style(`Args`, `Returns`) 포맷을 따르되 설명은 한국어로 작성 +- 커밋 메시지는 한국어 작성 (Conventional Commits 준수) +- 식별자(변수/함수명)는 영어 사용 + +### VI. 명시적 타입과 스타일 (Google Standard) +코드는 기계가 아닌 사람을 위해 작성한다. 가독성과 안정성을 최우선으로 한다: +- **Python (`src/`):** 모든 함수 인자와 반환값에 **Type Hint**를 반드시 명시한다. (`Any` 사용 지양) +- **TypeScript (`worker/`):** `interface` 정의를 강제하며, `any` 타입을 절대 사용하지 않는다. +- **Linter:** `ruff` 또는 `mypy` 검사를 통과하지 못한 코드는 커밋할 수 없다. + +### VII. 방어적 프로그래밍 (Stability) +시스템은 언제든 실패할 수 있다는 가정하에 설계한다: +- **No Silent Failures:** 외부 API(CCXT, Discord) 호출은 반드시 `try-except`로 예외를 처리한다. +- **Structured Logging:** `print()` 사용을 금지한다. `logger`를 사용하여 구조화된 로그(시간, 레벨, 메시지)를 남긴다. +- **Config Validation:** 환경변수나 설정 파일 로드 시, 필요한 값이 없으면 시스템 시작을 차단한다. + +## 레포지토리 구조 +(기존 내용 유지) + +## 협업 워크플로우 +(기존 내용 유지) + +## Governance +- 이 Constitution은 모든 개발 활동에 우선한다 +- 원칙 간 충돌 시 **보안(II) > 안정성(VII) > 나머지** 순으로 우선한다 + +**Version**: 1.1.0 | **Ratified**: 2026-02-09 | **Last Amended**: 2026-02-09 From e791cfdc164f926a06e53a1bb861067a329c8e00 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Mon, 9 Feb 2026 11:10:57 +0000 Subject: [PATCH 2/2] =?UTF-8?q?fix:=20CONSTITUTION.md=20=EB=A6=AC=EB=B7=B0?= =?UTF-8?q?=20=ED=94=BC=EB=93=9C=EB=B0=B1=20=EB=B0=98=EC=98=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 실제 레포 구조에 맞춰 디렉터리 경로 수정 (specs/docs → .specify/.claude 등) - worker/ → discord-github-worker/ 경로 수정 - .gitignore *.pem 요구사항을 권장 사항으로 완화 - pytest 강제를 unittest 마이그레이션 허용으로 수정 - ruff/mypy 강제를 권장 사항으로 완화 (향후 CI 도입 예정) Co-authored-by: sin seongsik --- CONSTITUTION.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/CONSTITUTION.md b/CONSTITUTION.md index 5e3caab..99e9fa3 100644 --- a/CONSTITUTION.md +++ b/CONSTITUTION.md @@ -6,14 +6,14 @@ 프로젝트는 세 개의 독립 영역으로 분리한다: - **비즈니스 로직** (`src/`): 트레이딩 전략, 백테스팅 엔진, 거래소 연동 등 핵심 도메인 코드 - **협업 툴** (`discord-github-worker/` 등): 봇, 자동화, 인프라 코드 -- **문서/명세** (`specs/`, `docs/`): 명세서, 설계 문서, 가이드 +- **문서/명세** (`.specify/`, `.claude/`, `.cursor/` 등): 명세서, 설계 문서, 가이드 각 영역은 독립적으로 개발/배포/테스트할 수 있어야 한다. 한 영역의 변경이 다른 영역에 영향을 주면 안 된다. ### II. 제로 시크릿 API 키, 토큰, 비밀번호, 개인 자격증명은 **절대** 커밋하지 않는다: - 모든 시크릿은 `.env` 파일 또는 플랫폼별 시크릿 관리 도구에 저장 -- `.gitignore`에 `.env`, `config.json`, `*.pem` 등 시크릿 파일 MUST 포함 +- `.gitignore`에 `.env`, `config.json` 등 시크릿 파일 패턴을 반드시 포함하고, 필요 시 `*.pem` 등 추가 시크릿 파일 패턴을 예시로 활용한다 - PR 리뷰 시 시크릿 유출 여부를 반드시 확인 - 실수로 커밋된 시크릿은 즉시 교체(revoke)하고 히스토리에서 제거 @@ -22,7 +22,10 @@ API 키, 토큰, 비밀번호, 개인 자격증명은 **절대** 커밋하지 - **Core Logic:** 트레이딩 전략, 주문 실행, 백테스팅 계산 로직은 **단위 테스트(Unit Test) 작성이 필수(MUST)**이다. - **Verification:** 백테스팅 결과 검증은 전략 변경 시 반드시 수행한다. - **Optional:** 단순 유틸리티, UI, 일회성 스크립트는 테스트 권장 사항(SHOULD)이다. -- 프레임워크: `pytest` 사용 +- **프레임워크 표준:** 신규/개편되는 Core Logic 테스트의 표준 러너는 `pytest`로 한다. + - 기존 `unittest` 기반 테스트는 점진적 마이그레이션 완료 시까지 허용하며, 혼합 기간 동안 두 러너 모두 통과해야 한다. + - `pytest` 도입 PR에서는 `requirements.txt`에 `pytest`를 추가하고, `README`/CI 설정에 `pytest tests/` 기준의 실행 방법을 명시해야 한다. + - 기존 `unittest` 테스트는 `python -m unittest`로 실행하며, `pytest` 도입 후에는 가능하면 테스트를 `pytest` 스타일로 변환한다. ### IV. PR 리뷰 필수 모든 Pull Request는 최소 1명의 리뷰어 승인 후 머지한다: @@ -32,7 +35,7 @@ API 키, 토큰, 비밀번호, 개인 자격증명은 **절대** 커밋하지 ### V. 한국어 우선 문서, 주석, 커밋 메시지는 한국어를 기본으로 한다: -- 명세서(`specs/`), README, 가이드 문서는 한국어 작성 +- 명세서(`.specify/`, `.claude/` 등), README, 가이드 문서는 한국어 작성 - **Docstring:** Google Style(`Args`, `Returns`) 포맷을 따르되 설명은 한국어로 작성 - 커밋 메시지는 한국어 작성 (Conventional Commits 준수) - 식별자(변수/함수명)는 영어 사용 @@ -40,8 +43,8 @@ API 키, 토큰, 비밀번호, 개인 자격증명은 **절대** 커밋하지 ### VI. 명시적 타입과 스타일 (Google Standard) 코드는 기계가 아닌 사람을 위해 작성한다. 가독성과 안정성을 최우선으로 한다: - **Python (`src/`):** 모든 함수 인자와 반환값에 **Type Hint**를 반드시 명시한다. (`Any` 사용 지양) -- **TypeScript (`worker/`):** `interface` 정의를 강제하며, `any` 타입을 절대 사용하지 않는다. -- **Linter:** `ruff` 또는 `mypy` 검사를 통과하지 못한 코드는 커밋할 수 없다. +- **TypeScript (`discord-github-worker/`):** `interface` 정의를 강제하며, `any` 타입을 절대 사용하지 않는다. +- **Linter:** `ruff` 및 `mypy` 검사를 통과하도록 코드를 작성하는 것을 권장한다. (향후 CI에서 자동 검사로 강제 예정) ### VII. 방어적 프로그래밍 (Stability) 시스템은 언제든 실패할 수 있다는 가정하에 설계한다: