에이전트 개발 규칙

이 문서는 AI 에이전트가 node-packages 모노레포에서 코드를 작성하고 기여할 때 따라야 하는 규칙과 가이드라인을 정의합니다.

목차

• 프로젝트 개요
• 코드 작성 규칙
• 커밋 규칙
• 보안 및 개인정보
• 파일 구조
• 코드 스타일
• 문서화
• 테스트
• 패키지 발행

---

프로젝트 개요

node-packages 는 hmmhmmhm 의 개인 연구용 npm 패키지 모노레포입니다. pnpm workspaces + Turborepo 구조로 운영되며, 현재 10개 패키지를 포함합니다.

• base2000, base6000 — 진수 변환·인코딩 실험
• biggest — 임의 정밀도 큰 수·소수 라이브러리
• curse-script — 텍스트 변환 실험
• edge-crypto — 엣지 런타임용 암호화 헬퍼
• gauss-spiral — 가우스 나선 좌표 시스템
• mugunghwa — 한글 기반 base 인코딩
• patternly — 패턴 매칭 유틸
• pseudo-shuffle — 순열 없는 가짜 셔플
• usernamer — 사용자명 생성기

각 패키지는 독립적으로 npm 에 발행되며, 공통 의존성·도구 설정은 루트에서 관리합니다.

---

코드 작성 규칙

파일 크기 제한

모든 코드 파일은 450줄 이하로 작성되어야 합니다.

• 최대 줄 수: 450줄
• 권장 줄 수: 300-400줄
• 초과 시 조치: 파일이 450줄을 초과하면 기능별로 분리하여 모듈화
• 예외: 자동 생성 파일(예: 빌드 산출물, lockfile) 은 예외로 둘 수 있음

파일 분리 예시

// ❌ 나쁜 예: 하나의 파일에 모든 기능 (600줄)
// packages/biggest/src/index.ts (600줄)

// ✅ 좋은 예: 기능별로 분리
// packages/biggest/src/integer.ts (200줄)
// packages/biggest/src/decimal.ts (180줄)
// packages/biggest/src/format.ts (120줄)
// packages/biggest/src/index.ts (50줄, re-export)

코드 품질

• 명확성: 코드는 명확하고 이해하기 쉽게 작성
• 재사용성: 중복 코드를 최소화하고 공통 로직은 함수로 추출
• 타입 안정성: TypeScript 의 타입 시스템을 적극 활용 (strict 모드 유지)
• 에러 핸들링: 모든 비동기 작업과 외부 API 호출에 적절한 에러 처리 구현
• 제로 의존성 지향: 가능한 한 외부 런타임 의존성을 추가하지 않습니다. 추가 시 합당한 사유를 PR 본문에 명시합니다.

예시

// ✅ 좋은 예
export function parse(input: string): Result {
  if (!input) {
    throw new TypeError("input must be a non-empty string");
  }
  return doParse(input);
}

// ❌ 나쁜 예
export function parse(input: any) {
  return doParse(input);
}

---

커밋 규칙

커밋 빈도

• 주기적인 커밋: 논리적인 작업 단위마다 커밋
• 작은 단위: 한 번에 하나의 기능이나 수정사항만 포함
• 완성된 코드: 빌드 실패나 런타임 에러가 없는 상태에서만 커밋

커밋 메시지 형식 (Conventional Commits)

<type>: <설명>

[선택: 본문]

• feat — 신규 기능
• fix — 버그 수정
• docs — 문서만 변경
• chore — 빌드/도구/의존성
• refactor — 동작 변경 없는 구조 개선
• test — 테스트 추가/수정
• perf — 성능 개선

예시

feat: add base6000 hangul-aware decoder
fix: handle negative zero in biggest comparison
chore: bump turbo to 2.x

---

보안 및 개인정보

• 비밀키·토큰·자격증명을 코드·테스트·문서에 포함하지 않습니다.
• 개인 정보(이메일, 실명) 를 예시 코드에 박지 않고, 의도된 mock 만 사용합니다.
• 보안 관련 변경(예: edge-crypto 의 알고리즘 변경) 은 별도 PR 로 분리하고 commit 메시지에 명시합니다.

---

파일 구조

node-packages/
├── packages/
│   └── <name>/
│       ├── src/
│       ├── tests/         (있는 경우)
│       ├── package.json
│       ├── tsconfig.json
│       └── README.md
├── package.json           (root, workspaces 정의)
├── pnpm-workspace.yaml
├── turbo.json
└── AGENTS.md / CLAUDE.md

각 패키지는 자기 자신의 package.json 을 가지며, npm 에 독립 발행됩니다.

---

코드 스타일

• 포매터: prettier (pnpm format)
• 린터: 각 패키지 단위로 turbo 가 위임 (pnpm lint)
• 타입 체크: pnpm check-types
• 빌드: pnpm build (turbo 가 의존 그래프에 따라 캐시·병렬 실행)

PR 제출 전 위 4개를 모두 통과시킵니다.

---

문서화

• 각 패키지는 자체 README.md 를 가지며, 설치·사용 예제·API 표를 포함합니다.
• 영어 README 를 우선하며, 한국어 README 는 선택적입니다 (있다면 영어와 동기 유지).
• 새 패키지 추가 시 root README.md 의 패키지 목록도 갱신합니다.

---

테스트

• 각 패키지는 자기에게 적합한 테스트 도구를 사용합니다 (Vitest 권장).
• 신규 함수·버그 수정에는 회귀 테스트를 동봉합니다.
• 외부 시스템에 의존하지 않는 단위 테스트만 운영합니다 (의존하면 mock 처리).

---

패키지 발행

• 각 패키지의 package.json 에 publishConfig.access = public 명시.
• 발행 전 pnpm build && pnpm check-types && pnpm lint 모두 통과 확인.
• 버전 범프는 SemVer 를 따릅니다. breaking change 는 major.
• npm 발행 토큰은 personal-agent/secrets/.npmrc.personal 을 사용합니다 (CI 가 아닌 로컬 발행 시).