diff --git a/.github/instructions/azure.instructions.md b/.github/instructions/azure.instructions.md index c77182b..6e044d1 100644 --- a/.github/instructions/azure.instructions.md +++ b/.github/instructions/azure.instructions.md @@ -2,24 +2,16 @@ applyTo: "**/*.py" --- -# Azure 프로젝트 공통 인스트럭션 +# Azure 인증 / 시크릿 컨벤션 -## Azure 인증 +## 인증 -- 로컬 개발 환경에서는 `AzureCliCredential`을 사용하고 `az login`으로 인증한다. -- 배포 환경에서는 `DefaultAzureCredential` / Managed Identity를 사용한다. -- 인증 객체와 Chat 클라이언트는 재사용하고, 요청마다 새로 생성하지 않는다. +- 로컬 개발은 `AzureCliCredential`(`azure-identity`)을 사용하고 `az login` 세션으로 인증한다(배포 환경은 `DefaultAzureCredential`/Managed Identity). +- 인증 객체와 `FoundryChatClient`는 재사용하고 요청마다 새로 만들지 않는다. +- API 키 기반 대신 passwordless 인증을 우선한다. -## 환경변수 / 시크릿 관리 +## 시크릿 / 보안 -- 환경변수는 `.env` 파일에 저장하고 `python-dotenv`로 로드한다. -- `.env` 파일은 `.gitignore`에 포함하여 절대 커밋하지 않는다. -- `.env.example`에 필요한 환경변수 키 목록을 공유한다. -- API 키, 엔드포인트 등 민감정보는 코드에 하드코딩하지 않는다. -- 필수 환경변수(`PROJECT_ENDPOINT` 등)는 앱 시작 시 검증하고, 누락 시 명확히 안내 후 종료한다. - -## 보안 - -- 엔드포인트 URL, 연결 문자열 등은 환경변수로 관리한다. -- 사용자 입력은 항상 검증한 후 사용한다. -- 로그에 민감정보(토큰, 키, 비밀번호)를 출력하지 않는다. +- 환경변수(`PROJECT_ENDPOINT`, `MODEL_DEPLOYMENT_NAME`)는 `.env`에서 `load_dotenv()`로 로드하고 코드에 하드코딩하지 않는다. `.env`는 커밋 금지(`.env.example`만 공유). +- 필수 환경변수는 누락 시 즉시 실패시키거나 명확한 한국어 안내 후 종료한다. +- 로그·출력에 토큰·키 등 민감정보를 남기지 않는다. diff --git a/.github/instructions/git-commit.instructions.md b/.github/instructions/git-commit.instructions.md index 87c826b..d286e9d 100644 --- a/.github/instructions/git-commit.instructions.md +++ b/.github/instructions/git-commit.instructions.md @@ -4,40 +4,17 @@ applyTo: "**" # Git 커밋 메시지 컨벤션 -> 이 규칙은 한국어 작성 컨벤션(`korean.instructions.md`)보다 **우선 적용**됩니다. -> 커밋 메시지는 오픈소스 관례·CI 도구·외부 기여자와의 호환성을 위해 영어로 통일합니다. +> 이 규칙은 `korean.instructions.md`보다 **우선 적용**한다(커밋 메시지는 영어로 통일). -## 언어 +- 모든 커밋 메시지(제목·본문)는 **영어**로 작성한다. 나머지 문서·주석·docstring은 한국어를 유지한다. +- 형식은 Conventional Commits `type(scope): subject` — `feat`·`fix`·`docs`·`refactor`·`test`·`chore`·`perf`·`style`. +- 제목은 50자 이내, 명령형 현재 시제, 끝에 마침표 없음. + - 좋은 예: `feat: add cost reviewer agent` / 나쁜 예: `feat: added agent`, `에이전트 추가` +- 본문이 필요하면 제목과 한 줄 띄우고 72자로 줄바꿈하며 "무엇을/왜"를 설명한다. +- 커밋 전 `.env` 등 시크릿이 스테이징되지 않았는지 확인한다(`.env.example`만 포함). -- 모든 커밋 메시지(제목·본문)는 **영어**로 작성한다. -- 코드 주석·docstring·README 등 나머지 문서는 기존대로 한국어를 유지한다. +## 트레일러 (항상 포함) -## 형식 (Conventional Commits) - -- 형식: `type(scope): subject` -- 사용 가능한 `type`: - - `feat` — 새 기능 / `fix` — 버그 수정 / `docs` — 문서만 변경 - - `refactor` — 기능 변화 없는 리팩터링 / `test` — 테스트 / `chore` — 부수 작업 - - `perf` — 성능 개선 / `style` — 포매팅 - -## 작성 규칙 - -- 제목은 **50자 이내**, **명령형 현재 시제**(imperative mood)로 작성한다. - - 좋은 예: `feat: add refund specialist agent` - - 나쁜 예: `feat: added refund agent` / `feat: 환불 에이전트 추가` -- 제목 끝에 마침표를 붙이지 않는다. -- 본문이 필요하면 제목과 한 줄 띄우고 **72자 단위로 줄바꿈**하며 "무엇을/왜"를 설명한다. - -## 트레일러 - -- 이 프로젝트에서는 다음 트레일러를 항상 포함한다: - - ``` - Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> - ``` - -## PR 생성 워크플로우 - -- 기능/수정 브랜치(`feat/*`, `fix/*`, `docs/*` 등)에 푸시한 직후 PR을 생성한다. -- PR 생성은 `gh pr create --draft --base main --head `를 사용한다 (AGENTS.md 준수). -- PR 제목과 본문도 커밋 메시지와 동일하게 **영어**로 작성한다. +``` +Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> +``` diff --git a/.github/instructions/korean.instructions.md b/.github/instructions/korean.instructions.md index 10bd934..a25b647 100644 --- a/.github/instructions/korean.instructions.md +++ b/.github/instructions/korean.instructions.md @@ -4,20 +4,11 @@ applyTo: "**" # 한국어 작성 컨벤션 -## 언어 규칙 +- 응답·주석·docstring·사용자 메시지·문서(README·가이드)는 **한국어**로 작성한다. +- 코드 식별자(변수·함수·클래스명)·SDK 클래스/메서드명·환경변수 키(`PROJECT_ENDPOINT` 등)는 **영어** 그대로 둔다. +- 기술 용어는 한국어로 쓰되 통용 영문은 괄호 병기한다(예: 검색 증강 생성(RAG), 멀티 에이전트(multi-agent)). +- 주석은 꼭 필요한 곳에만 간결하게 단다. -- 모든 응답, 주석, docstring, 사용자 메시지는 **한국어**로 작성한다. -- 코드 내 변수명, 함수명, 클래스명은 **영어**를 사용한다. -- 기술 용어는 한국어로 번역하되, 통용되는 영문 용어는 괄호로 병기한다. - - 예: 검색 증강 생성(RAG), 모델 컨텍스트 프로토콜(MCP) +## 예외 (영어 유지) -## 주석 및 문서 - -- 코드 주석은 한국어로 간결하게 작성한다. -- 함수 docstring은 Google 스타일로 작성하며, 설명/Args/Returns를 한국어로 작성한다. -- README, 가이드 문서는 한국어로 작성한다. - -## 사용자 메시지 - -- 콘솔 출력, 에러 메시지, 상태 메시지는 한국어로 작성한다. -- 에이전트의 `instructions`와 응답도 한국어로 작성한다. +- Git 커밋 메시지·PR 제목/본문은 영어로 작성한다(`git-commit.instructions.md` 우선 적용). diff --git a/.github/instructions/python.instructions.md b/.github/instructions/python.instructions.md index c86835b..02ede37 100644 --- a/.github/instructions/python.instructions.md +++ b/.github/instructions/python.instructions.md @@ -2,30 +2,29 @@ applyTo: "**/*.py" --- -# Python 프로젝트 공통 인스트럭션 +# Python 코드 컨벤션 -## 가상환경 설정 +## 환경 / 실행 -- Python 3.14.5 기반 `.venv` 가상환경을 사용한다 (`.venv/`는 `.gitignore`로 버전 관리에서 제외). -- 생성·활성화 후 가상환경 안에서 패키지를 설치한다: +- **Python 3.14.5** 사용(실습 표준; MAF 공식 최소 요구는 3.13). +- 프로젝트 루트에서 가상환경을 만들고 의존성을 설치한다: ```bash - python -m venv .venv - source .venv/bin/activate # macOS/Linux (Windows: .venv\Scripts\activate) + python3 -m venv .venv + source .venv/bin/activate # macOS/Linux (Windows: .venv\Scripts\Activate.ps1) pip install -r requirements.txt ``` +- `.venv/`는 `.gitignore`로 버전 관리에서 제외한다. -## 의존성 관리 +## 의존성 -- 의존성은 `requirements.txt`에 명시하고, 패키지를 추가하면 갱신한다. -- 재현성을 위해 버전을 명시한다: SDK·핵심 패키지는 `==` 또는 `>=x,=` 최소 버전 지정도 허용. +- 의존성은 루트 `requirements.txt`에 명시하고, 패키지를 추가하면 갱신한다. +- 메타 패키지 `agent-framework`(foundry·orchestrations 포함)를 사용한다. +- SDK·핵심 패키지는 `>=x`로 최소 버전을 명시해 재현성을 유지한다(프리릴리스 허용). -## 코드 컨벤션 +## 코드 스타일 -- 한국어 주석과 docstring을 사용한다. -- 모듈 최상단에 모듈 설명 docstring을 작성한다. -- 함수에는 Args/Returns를 포함한 Google 스타일 docstring을 작성한다. +- 모듈 최상단에 한국어 모듈 docstring을 둔다. +- 함수는 Google 스타일 한국어 docstring(설명/Args/Returns; 자명한 헬퍼는 생략 가능)을 작성한다. - 타입 힌트를 적극 활용한다. -- import 순서: 표준 라이브러리 → 서드파티 → 로컬 모듈 (각 그룹 사이에 빈 줄). -- 모든 에이전트/IO 호출은 `async/await`로 작성하고, 진입점은 - `if __name__ == "__main__": asyncio.run(main())` 형태를 따른다. -- 예외는 `try/except`로 감싸고 사용자 친화적인 한국어 메시지를 출력한다. +- import 순서: 표준 라이브러리 → 서드파티 → 로컬(그룹 사이 빈 줄). +- 비동기 호출(`async/await`)·진입점(`asyncio.run(main())`)·`load_dotenv()` 규칙은 `copilot-instructions.md`「핵심 제약」을 따른다.