CLI

PleaseAI 코드 스타일을 한 번의 명령으로 설정 — 패키지 설치와 설정 파일 작성까지.

@pleaseai/code-style는 PleaseAI의 공유 코드 스타일을 어떤 프로젝트에도 적용해 주는 제로 설정 CLI입니다. ESLint / Prettier / EditorConfig 패키지를 설치하고, AI 코딩 어시스턴트가 처음부터 린트를 통과하는 코드를 작성할 수 있도록 AGENTS.md 규칙 블록을 관리합니다.

ultracite와 네이버페이의 @naverpay/code-style-cli에서 영감을 받았습니다.

빠른 시작

package.json이 있는 프로젝트 루트에서 실행하세요:

CLI는 다음을 수행합니다:

lockfile에서 패키지 매니저를 감지합니다 (bun → pnpm → yarn → npm, 기본값은 bun)
사용 가능한 도구를 체크박스 UI로 표시합니다. 이미 설치된 항목은 (installed)로 표시됩니다
선택한 패키지를 dev dependency로 설치합니다
해당 설정 파일을 작성하거나 업데이트합니다

명령어

`init`

대화형 설정 — 서브커맨드를 지정하지 않으면 기본 동작입니다.

pleaseai-code-style init
pleaseai-code-style init --yes   # 비대화형, 기본값 수락

`update`

패키지나 다른 설정 파일을 건드리지 않고 AGENTS.md 규칙 블록 만 새로 고칩니다. @pleaseai/code-style을 업그레이드한 뒤 최신 규칙을 적용할 때 사용하세요.

pleaseai-code-style update

`doctor`

현재 프로젝트의 설정 상태를 보고합니다 — 어떤 패키지가 설치되어 있고, 어떤 설정 파일이 존재하는지 확인할 수 있습니다.

pleaseai-code-style doctor

`check`

파일 이름, 테스트 경로, 공유 테스트 헬퍼를 ADR-0022 code-organization 표준(3층)에 맞춰 검사합니다. 구조 규칙(2층)은 ast-grep 도구가 sgconfig.yml에 연결해 주는 @pleaseai/ast-grep-config 규칙으로 ast-grep scan을 따로 실행합니다.

check는 CLI에 번들된 @pleaseai/ast-grep-config의 추출 규칙을 @ast-grep/cli의 ast-grep 바이너리로 실행합니다. 바이너리는 검사하는 프로젝트에서 먼저 찾고, 프로젝트에 있는 추출 규칙 사본은 마지막 대안으로만 씁니다. 둘 다 dev dependency로 설치하세요 — 바이너리는 check용, 패키지는 ast-grep scan 규칙용입니다(init의 ast-grep 도구가 설치해 줍니다):

bun add -D @pleaseai/ast-grep-config @ast-grep/cli

please-style check              # 현재 디렉터리 검사
please-style check packages/    # 하위 디렉터리 검사
please-style check --json       # 기계가 읽는 출력
please-style check --strict     # 발견 사항이 있으면 exit 1 (위반을 없앤 뒤 CI용)

플래그	설명
`[path]`	검사할 디렉터리 (기본값: 현재 디렉터리)
`--json`	결과를 JSON(`root`, `findings`, `notices`)으로 출력
`--strict`	발견 사항이 하나라도 있으면 exit 1 (기본: 경고만)
`--config <file>`	설정 파일 (기본값: 둘러싼 프로젝트 루트의 `code-organization.json`, 위쪽에 프로젝트 표지 파일이 없으면 `<path>`의 것)

종료 코드: 0 발견 사항 없음 또는 경고만, 1 --strict에서 발견 사항 있음, 2 사용법 오류, 설정 오류, 또는 추출이 필요한 파일이 있는데 @ast-grep/cli를 찾지 못함.

선택 설정 파일 code-organization.json은 이름을 추가만 할 수 있습니다 — TypeScript sourceRoots와 테스트 envSegments를 더할 수 있고, 테스트를 소스 옆에 두거나 검사를 끄는 옵션은 없습니다. 전체 검사 내용은 CLI README를 참고하세요.

지원 도구

도구	npm 패키지	설정 파일
eslint-config	`@pleaseai/eslint-config`, `eslint`	`eslint.config.mjs`
prettier-config	`@pleaseai/prettier-config`, `prettier`	`package.json#prettier`
editorconfig	`@pleaseai/editorconfig`	`.editorconfig`
agents-md	—	`AGENTS.md` (마커로 관리되는 블록)
ast-grep	`@pleaseai/ast-grep-config`, `@ast-grep/cli`	`sgconfig.yml`
bun-lint-config	`@pleaseai/bun-lint-config`	`bunfig.toml`의 `[lint]` (마커로 관리되는 블록)

init --yes는 bun-lint-config를 뺀 모든 도구를 적용합니다. bun lint는 ESLint에 더하는 도구가 아니라 ESLint를 대신하는 도구이므로, 대화형 init에서 직접 선택해야 합니다.

`AGENTS.md` 규칙 블록

CLI는 AGENTS.md에 마커로 구분된 블록을 작성하므로, 주변에 직접 작성한 내용을 섞어 두어도 다음 실행 시 사라지지 않습니다:

AGENTS.mdmd

내 프로젝트 노트는 여기에 있습니다.

<!-- pleaseai-code-style:start -->
# PleaseAI Code Style

이 규칙은 `@pleaseai/code-style`에서 관리합니다.
`pleaseai-code-style update`를 실행하면 이 블록이 새로고침됩니다.

- 포매터: `@pleaseai/eslint-config` (`@antfu/eslint-config`를 감쌈)
- 세미콜론 없음, 홑따옴표, 공백 2칸 들여쓰기, trailing comma, LF 개행
- ESM만 사용 — `require`/`module.exports` 사용 금지
- ...
<!-- pleaseai-code-style:end -->

내 콘텐츠는 그대로 유지됩니다.

CLI는 두 마커 주석 사이의 내용 만 관리하며 — AGENTS.md의 나머지 내용은 그대로 보존됩니다. update를 연속으로 두 번 실행해도 no-op이며, 블록이 중복되지 않습니다.

전체 원본 규칙 목록은 AI 어시스턴트가 긴 버전을 읽기 원할 때 참고할 수 있도록 node_modules/@pleaseai/code-style/rules.md로 함께 배포됩니다.

옵션

플래그	설명
`--yes`, `-y`	기본값(opt-in인 bun-lint-config를 뺀 모든 도구)을 수락하고 기존 파일을 확인 없이 덮어씀
`--lang <ko\|en>`	CLI 언어 강제 지정 (기본값은 `$LC_ALL` / `$LANG`)
`--help`, `-h`	도움말 출력
`--version`, `-v`	CLI 버전 출력

현지화

CLI는 LC_ALL, LANG, LC_MESSAGES에서 locale을 자동 감지하며, 현재 한국어와 영어 메시지를 제공합니다. --lang ko 또는 --lang en으로 강제 지정할 수 있습니다:

pleaseai-code-style --lang ko init

CI에서의 사용

--yes와 언어 옵션을 조합하면 CI나 프로젝트 템플릿에 적합한 완전 비대화형 실행을 만들 수 있습니다:

pleaseai-code-style --yes --lang en init

opt-in인 bun-lint-config를 뺀 모든 도구를 적용하고, 기존 설정 파일을 덮어쓰며, 영어로 출력합니다.

바이너리

패키지는 두 개의 bin 엔트리를 노출합니다 — 원하는 것을 사용하세요:

pleaseai-code-style
please-style (짧은 별칭)

둘 다 동일한 실행 파일을 가리킵니다.

빠른 시작

명령어

init

update

doctor

check