@pleaseai/code-style는 PleaseAI의 공유 코드 스타일을 어떤 프로젝트에도 적용해 주는 제로 설정 CLI입니다. ESLint / Prettier / EditorConfig 패키지를 설치하고, AI 코딩 어시스턴트가 처음부터 린트를 통과하는 코드를 작성할 수 있도록 AGENTS.md 규칙 블록을 관리합니다.
ultracite와 네이버페이의 @naverpay/code-style-cli에서 영감을 받았습니다.
빠른 시작
프로젝트 루트에서 실행하세요. package.json은 필수가 아닙니다. 없는 프로젝트(Gradle, pubspec, Cargo 전용)에서는 init이 AGENTS.md 블록과 가이드만 제공하며, update와 doctor는 그대로 동작합니다:
bunx @pleaseai/code-stylepnpm dlx @pleaseai/code-stylenpx @pleaseai/code-styleCLI는 다음을 수행합니다:
- lockfile에서 패키지 매니저를 감지합니다 (bun → pnpm → yarn → npm, 기본값은 bun)
- 사용 가능한 도구를 체크박스 UI로 표시합니다. 이미 설치된 항목은
(installed)로 표시됩니다 - 선택한 패키지를 dev dependency로 설치합니다
- 해당 설정 파일을 작성하거나 업데이트합니다
명령어
init
대화형 설정 — 서브커맨드를 지정하지 않으면 기본 동작입니다.
pleaseai-code-style init
pleaseai-code-style init --yes # 비대화형, 기본값 수락update
패키지나 다른 설정 파일을 건드리지 않고 AGENTS.md 규칙 블록과 .agents/code-style/의 가이드를 새로 고칩니다. @pleaseai/code-style을 업그레이드한 뒤 최신 규칙을 적용할 때 사용하세요.
pleaseai-code-style updatedoctor
현재 프로젝트의 설정 상태를 보고합니다 — 어떤 패키지가 설치되어 있고, 어떤 설정 파일이 존재하는지 확인할 수 있습니다.
pleaseai-code-style doctorcheck
파일 이름, 테스트 경로, 공유 테스트 헬퍼를 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/cliplease-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 |
AGENTS.md 규칙 블록
CLI는 AGENTS.md에 마커로 구분된 블록을 작성하므로, 주변에 직접 작성한 내용을 섞어 두어도 다음 실행 시 사라지지 않습니다:
내 프로젝트 노트는 여기에 있습니다.
<!-- pleaseai-code-style:start -->
# Passion Factory 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 -->
내 콘텐츠는 그대로 유지됩니다.AGENTS.md에서 CLI는 두 마커 주석 사이의 내용 만 관리하며 — 나머지 내용은 그대로 보존됩니다. update를 연속으로 두 번 실행해도 no-op이며, 블록이 중복되지 않습니다.
전체 원본 규칙은 AI 어시스턴트가 긴 버전을 읽기 원할 때 참고할 수 있도록 언어별로 나뉘어 프로젝트에 복사되므로 node_modules 없이도 읽을 수 있습니다. .agents/code-style/general.md(모든 언어)를 먼저 읽고, 사용하는 언어의 가이드를 읽으세요(예: TypeScript·JavaScript는 .agents/code-style/typescript.md). 같은 디렉터리의 NOTICE.md와 LICENSE-Apache-2.0.txt에 각색한 가이드의 출처 표기가 있습니다. .agents/code-style/은 커밋하세요. init과 update가 이 디렉터리를 다시 쓰며 파일을 덮어쓰고, 더 이상 선택하지 않은 언어의 가이드는 삭제합니다(디렉터리의 다른 파일은 건드리지 않습니다). doctor는 블록이 가리키는 가이드가 모두 있는지 확인합니다.
옵션
| 플래그 | 설명 |
|---|---|
--yes, -y |
기본값을 수락하고 기존 파일을 확인 없이 덮어씀 |
--lang <list> |
AGENTS.md 룰 블록에 넣을 언어, 쉼표로 구분 (init/doctor: 자동 감지, update: 블록에 이미 있는 언어, 아래 참고) |
--locale <ko|en> |
CLI 언어 강제 지정 (기본값은 $LC_ALL / $LANG) |
--help, -h |
도움말 출력 |
--version, -v |
CLI 버전 출력 |
언어
--lang <list>는 AGENTS.md 룰 블록이 가리킬 프로그래밍 언어를 고릅니다. 예: --lang typescript,dart. 지원 값은 typescript, dart, rust, java, go, python, ruby, csharp, html-css입니다. 옵션이 없으면 init이 프로젝트 루트의 마커 파일로 언어를 감지합니다. package.json 또는 tsconfig.json(typescript), pubspec.yaml(dart), Cargo.toml(rust), build.gradle, build.gradle.kts, pom.xml(java), go.mod(go), pyproject.toml(python)이 해당합니다. 대화형 init은 감지된 목록을 조정할 수 있게 합니다. update는 --lang을 주지 않으면 기존 블록이 가리키는 언어를 유지합니다. 알 수 없는 --lang 값은 지원하는 언어 목록과 함께 오류로 종료합니다(종료 코드 1). doctor는 감지된 언어를 보여줍니다.
현지화
CLI는 LC_ALL, LANG, LC_MESSAGES에서 locale을 자동 감지하며, 현재 한국어와 영어 메시지를 제공합니다. --locale ko 또는 --locale en으로 강제 지정할 수 있습니다:
pleaseai-code-style --locale ko init--lang ko와 --lang en은 사용 중단된 로케일 별칭입니다. 당분간은 로케일을 지정하며 사용 중단 경고를 출력하고, 언어는 선택하지 않습니다. --lang ko|en과 --locale을 함께 주면 --locale이 우선합니다. 지원하지 않는 --locale 값도 오류로 종료합니다(종료 코드 1).
CI에서의 사용
--yes와 언어 옵션을 조합하면 CI나 프로젝트 템플릿에 적합한 완전 비대화형 실행을 만들 수 있습니다:
pleaseai-code-style --yes --locale en init모든 도구의 기본값을 수락하고, 기존 설정 파일을 덮어쓰며, 영어로 출력합니다.
바이너리
패키지는 두 개의 bin 엔트리를 노출합니다 — 원하는 것을 사용하세요:
pleaseai-code-styleplease-style(짧은 별칭)
둘 다 동일한 실행 파일을 가리킵니다.