MINARA규약
모든 Minara 기여가 지켜야 하는 엔지니어링 및 콘텐츠 규칙
먼저 저장소 전체 CONTRIBUTING 가이드에서 기여 경로, 개발 환경 설정, Pull Request 요구사항, 라이선스 정책을 확인하세요. 편집하기 전에 루트 CLAUDE.md, 가장 가까운 패키지 가이드, 변경 경로에 해당하는 모든 .claude/rules/*.md도 읽어야 합니다.
1. 가장 작은 확장 지점 선택하기
기존 도구로 구성하는 지침, 도메인 지식, 반복 가능한 흐름은 스킬로 만듭니다. 결정론적 처리, 인증, 바이너리나 스트리밍 데이터, 새로운 실행 경계가 필요하면 도구를 추가합니다. 공유 타입과 UI는 알맞은 패키지에 두고 앱 전용 동작은 해당 앱에 둡니다.
Minara의 내부 도구 레지스트리에 맞는 기능을 위해 별도 MCP 배관을 추가하지 마세요.
2. 비밀 정보를 프롬프트와 소스에서 분리하기
자격 증명은 팩토리 생성 시 process.env에서 읽습니다. 타입이 정의된 환경 변수 문서 소스에 선언을 추가하고 .env.example과 공개 환경 변수 문서를 다시 생성하세요. 스킬은 metadata.minara.requires_env로 의존성을 선언하고, 선택적 공급자 자격 증명이 없으면 도구 팩토리는 []를 반환합니다.
비밀 정보를 하드코딩하거나 LLM에 보이는 도구 인자로 받지 마세요. 테스트, fixture, 스크린샷, 로그에도 실제 자격 증명을 넣지 않습니다.
3. 안전 경계 보존하기
파일 시스템 도구는 apps/agent/src/tools/_security/sandbox.ts를 통해 경로를 해석합니다. 하위 프로세스 도구는 기존 명령 가드와 OS 격리를 사용합니다. 이 경계를 우회하는 별도 도우미를 만들지 마세요.
자금을 이동하는 모든 도구는 isFundMoving: true와 controlPolicy.confirm 미리보기를 선언합니다. 공통 권한 게이트가 확인을 담당하고 핸들러는 승인된 요청만 실행합니다. 이 영역을 바꾸기 전에 가장 가까운 기존 도구와 자금 이동 규칙을 확인하세요.
4. TypeScript ESM 호환성 유지하기
TypeScript 소스의 상대 import에는 .js 확장자를 사용하고 타입 전용 import에는 import type을 사용합니다.
import { createThing } from "./thing.js";
import type { ToolEntry } from "../core/tool-registry.js";5. 스킬 ID를 소스에서 복사하기
역사적인 이유로 스킬 ID에는 점, 하이픈, 밑줄이 섞여 있습니다. 디렉터리 이름에서 추측하지 말고 유효한 SKILL.md의 metadata.minara.id를 복사하세요.
rg "id:" apps/agent/src/skills/builtin/*/SKILL.md내장 로더는 builtin/의 바로 아래 디렉터리만 탐색합니다. 패키지를 추가하거나 제거할 때 apps/agent/tests/unit/skills/builtin-catalog-guard.test.ts의 ID도 함께 수정합니다.
6. 공개 계약과 문서 동기화하기
HTTP 경로를 변경하면 경로 명세와 생성된 API/OpenAPI 결과를 갱신합니다. CLI 또는 REPL 명령을 변경하면 reference/cli/의 해당 페이지를 수정합니다. 새 도구는 도구 세트에 추가하고 도구 문서를 다시 생성합니다.
REPL 명령에 필수 인자가 없으면 사용법 오류만 반환하지 말고 대화형으로 안내합니다. 명령 이름은 /agent-run처럼 평평한 하이픈 형식을 유지합니다.
직접 작성한 공개 문서는 영어, 중국어, 일본어, 한국어로 함께 배포합니다. 네 개의 형제 파일을 동시에 수정하고 내부 링크는 /docs/features/portfolio처럼 로케일을 포함하지 않습니다.
7. 올바른 경계에서 테스트하기
단위 테스트부터 시작합니다. SQLite, CLI, 게이트웨이, 실제 로컬 구성 요소 경계에는 통합 테스트를 사용하고 완전한 사용자 흐름에는 E2E 테스트를 사용합니다. 테스트는 운영 자격 증명 없이 실행되어야 하며 로컬 상태를 격리해야 합니다.
좁은 테스트를 먼저 실행한 다음 타입 검사와 영향을 받는 더 넓은 스위트를 실행합니다. Pull Request에 test.only나 불안정한 시간 가정을 남기지 마세요.
8. 출처와 라이선스 존중하기
프로젝트 조건으로 라이선스할 권리가 있는 코드, 데이터, 프롬프트, 미디어만 제출하고 필요한 고지를 보존하세요. 외부 자료의 라이선스를 알 수 없거나 찾을 수 없다면 확인이 끝날 때까지 도입을 중단합니다.
Minara.AI 독점 자산, 사용자 거래 데이터, 모델 가중치, 출처와 권리를 설명할 수 없는 생성물을 제출하지 마세요.
변경 범위 집중하기
- 기능 변경에 관련 없는 정리를 섞지 않습니다.
- 내부 도구 레지스트리에 맞는 기능을 위해 MCP 배관을 추가하지 않습니다.
- 비밀 정보를 하드코딩하거나 LLM에 보이는 도구 인자로 받지 않습니다.
- 구체적인 반복 필요가 없는 추상화를 추가하지 않습니다.
- 코드를 그대로 설명하는 주석을 쓰지 않습니다.
- 발생할 수 없는 조건을 위한 오류 처리를 추가하지 않습니다.
- 이 Node 저장소에 Python을 추가하지 않습니다.
.env,.minara/,sandbox/,dist/, 로컬 DB 파일을 커밋하지 않습니다.- 비 OSS 콘텐츠를
apps/agent/src/skills/external/에 추가하지 않습니다. - 생성된 문서를 직접 편집하지 않고 소스를 수정한 뒤 다시 생성합니다.