사용 전후

빈 폴더에서 같은 요청을 claude -p로 두 번 실행했습니다. 한 번은 Claude Code만, 한 번은 ai-design을 켜고 실행했으며, 요청에는 쓸 수 있는 사실을 모두 적었습니다. 결과 파일은 고치지 않고 site/samples/claude/에 그대로 두었습니다.

shipit 소개 랜딩 페이지를 index.html 한 파일로 만들어 줘 (Tailwind CDN 사용 가능). 알려진 사실은 다음이 전부야.
- shipit: 사내 배포 도구. 명령 하나(`shipit deploy staging`)로 스테이징에 배포
- 배포 시간: 수동 평균 25분 → shipit 평균 4분 (2026년 3분기 사내 측정, 배포 212건)
- 필요 조건: Kubernetes 1.28 이상, kubectl 로그인
- 설치: `brew install acme/tap/shipit`, 롤백: `shipit rollback`

랜딩 페이지에서 달라진 점

아래는 Claude가 index.html을 쓴 직후 수정 직후 검사가 Claude에게 돌려준 내용입니다. 경로만 줄였습니다.

ai-design style check (github.com/jungrok5/ai-design, docs/standard.md) found AI-tone/AI-look patterns in the lines you just wrote. Fix the ones that are real in this context, only in those lines (keep facts, names and code unchanged; do not rewrite text you were not asked to touch); leave deliberate quotes with a `style-ignore` marker.
index.html:92:3 warning [ui-raw-color] "border-left: 1px solid #2c383b" — Raw color outside the design tokens → var(--token) from the design system (default: polish-ui/design/tokens.css in ai-design); add a token if none fits
index.html:99:15 warning [ui-raw-color] "background: #1d282b" — Raw color outside the design tokens → var(--token) from the design system (default: polish-ui/design/tokens.css in ai-design); add a token if none fits

출시 공지 글

같은 사실로 사내 블로그용 출시 공지를 요청했습니다. ai-design을 켠 쪽은 polish-writing을 읽었습니다. 아래 검사 결과는 1.3.0 검사기로 지금 다시 실행한 것입니다.

# shipit 출시: 명령 하나로 스테이징 배포

스테이징 배포를 위한 사내 배포 도구 **shipit**을 출시했습니다. 이제 명령 하나로 스테이징에 배포할 수 있습니다.

```bash
shipit deploy staging
```

## 얼마나 빨라졌나요?

2026년 3분기 사내 측정 결과(배포 212건 기준), 평균 배포 시간은 다음과 같이 줄었습니다.

| 방식 | 평균 배포 시간 |
| --- | --- |
| 수동 배포 | 25분 |
| shipit | 4분 |

## 사용 조건

- Kubernetes 1.28 이상
- kubectl 로그인 상태

## 설치

```bash
brew install acme/tap/shipit
```

## 롤백

배포에 문제가 생기면 다음 명령으로 되돌릴 수 있습니다.

```bash
shipit rollback
```

## 문의

사용 중 궁금한 점이 있으면 **#platform** 채널로 문의해 주세요.

$ python3 style_check.py claude/notice-without.md
claude/notice-without.md:9:1 warning [ko-question-heading] "## 얼마나 빨라졌나요?" — 질문형 제목 (FAQ가 아닌 절) → 그 절이 말하는 사실을 제목으로 (예: '얼마나 빨라졌나요?' → '배포 시간')
style: 0 error(s), 1 warning(s) in 1 file(s)
exit 0

# shipit 출시: 명령 하나로 스테이징 배포

shipit은 스테이징 배포를 명령 하나로 실행하는 사내 배포 도구입니다. 오늘부터 사용할 수 있습니다.

```bash
shipit deploy staging
```

## 배포 시간

2026년 3분기에 사내에서 배포 212건을 측정했습니다. 수동 배포는 평균 25분, shipit 배포는 평균 4분이 걸렸습니다.

| 방식 | 평균 배포 시간 |
| --- | --- |
| 수동 | 25분 |
| shipit | 4분 |

## 사용 조건

- Kubernetes 1.28 이상
- kubectl 로그인 완료

## 설치

```bash
brew install acme/tap/shipit
```

## 롤백

배포를 되돌릴 때는 다음 명령을 실행합니다.

```bash
shipit rollback
```

## 문의

사용 중 막히는 부분이나 질문은 #platform 채널에 남겨 주세요.

$ python3 style_check.py claude/notice-with.md
style: 0 error(s), 0 warning(s) in 1 file(s)
exit 0

README 작업도 같은 방식으로 비교했는데, 두 결과의 차이는 "왜 shipit인가"라는 절 제목 하나였습니다. 세 작업 중 차이가 가장 컸던 것은 랜딩 페이지였습니다.

# shipit

명령 하나로 스테이징에 배포하는 사내 배포 도구입니다.

```bash
shipit deploy staging
```

## 왜 shipit인가

수동 배포는 평균 25분이 걸렸지만, shipit은 평균 4분이면 끝납니다.

| 방식 | 평균 배포 시간 |
| --- | --- |
| 수동 배포 | 25분 |
| shipit | 4분 |

> 2026년 3분기 사내 측정 기준 (배포 212건)

## 필요 조건

- Kubernetes 1.28 이상
- kubectl 로그인

## 설치

```bash
brew install acme/tap/shipit
```

## 사용법

### 스테이징 배포

```bash
shipit deploy staging
```

### 롤백

```bash
shipit rollback
```

# shipit

shipit은 명령 하나로 스테이징에 배포하는 사내 배포 도구입니다.

```sh
shipit deploy staging
```

## 배포 시간

사람이 수동으로 배포할 때 평균 25분이 걸렸고, shipit으로는 평균 4분이 걸렸습니다.

| 방식 | 평균 배포 시간 |
| --- | --- |
| 수동 배포 | 25분 |
| shipit | 4분 |

2026년 3분기 사내 측정 결과이며, 배포 212건을 기준으로 합니다.

## 필요 조건

- Kubernetes 1.28 이상
- kubectl 로그인

## 설치

```sh
brew install acme/tap/shipit
```

## 사용법

스테이징에 배포합니다.

```sh
shipit deploy staging
```

배포를 롤백합니다.

```sh
shipit rollback
```

# AEO 검사

혁신적인 AI 기반 분석으로 당신의 브랜드 경쟁력을 획기적으로 강화하세요!
강력한 AI가 다양한 검색 엔진을 통해 콘텐츠를 분석하는 것이 중요합니다.
결론적으로, 지금이야말로 AEO를 시작할 때입니다.

$ python3 style_check.py landing-before.md
landing-before.md:3:1 error [ko-hype] "혁신적" — 근거 없는 과장 수식어 → 무엇이 얼마나 나아지는지 숫자나 동작으로 서술 (예: 응답 1 ms 이하)
landing-before.md:4:1 error [ko-ai-boilerplate] "강력한 AI" — AI가 자주 쓰는 상투 문구 → 제품이 실제로 하는 일로 교체
landing-before.md:4:33 warning [ko-must-important] "것이 중요합니다" — '~하는 것이 중요합니다' → 해야 할 일을 바로 서술 (예: 매일 백업합니다)
landing-before.md:5:1 error [ko-closing-formula] "결론적으로" — 결말 공식 → 요약 접속어 삭제, 마지막 사실로 마무리
landing-before.md:5:8 error [ko-now-is-the-time] "지금이야말로" — 선동형 결말 → 지금 하면 달라지는 점을 서술
style: 4 error(s), 1 warning(s) in 1 file(s)
exit 1

# AEO 검사

URL을 입력하면 ChatGPT, Perplexity, Gemini의 답변이 그 사이트를 인용하는지 검사합니다.
인용되지 않은 질문마다 고칠 항목을 함께 보여 줍니다.

$ python3 style_check.py landing-after.md
style: 0 error(s), 0 warning(s) in 1 file(s)
exit 0

<section class="text-center py-24 bg-gradient-to-r from-indigo-500 via-purple-500 to-pink-500">
  <h1 class="text-6xl font-bold bg-clip-text text-transparent">🚀 Unlock the Power of Data</h1>
  <button class="rounded-2xl shadow-2xl transition-all animate-bounce">Get Started →</button>
  <p>Trusted by 10,000+ teams ★★★★★</p>
</section>

$ python3 style_check.py card-before.html
card-before.html:1:52 error [ui-purple-gradient] "from-indigo-500" — AI default purple/indigo gradient → use the product's color tokens; solid surfaces
card-before.html:2:33 error [ui-gradient-text] "bg-clip-text text-transparent" — Gradient-filled text → one solid color; emphasize with size or weight
card-before.html:2:64 error [ui-emoji-heading] "🚀" — Emoji used as an icon in a heading, button, link or list item → SVG icon with aria-hidden, or nothing
card-before.html:2:66 error [en-hype] "Unlock the Power" — Sales language → say what the user can do, with a number if you have one
card-before.html:3:41 warning [ui-transition-all] "transition-all" — transition: all → list the properties (opacity, transform)
card-before.html:3:56 warning [ui-bounce] "animate-bounce" — Bounce / pulsing animation → ease-out 150–250 ms, and only where it explains a change
card-before.html:4:6 error [ui-fake-social-proof] "Trusted by 10,000+" — Placeholder or invented social proof → real quotes, logos and numbers only
style: 5 error(s), 2 warning(s) in 1 file(s)
exit 1

<section class="hero">
  <h1>읽기 응답 1 ms 미만의 인메모리 DB</h1>
  <p>p99 기준, 단일 노드 벤치마크 결과입니다.</p>
  <div class="ds-cmd"><code>SET user:1 "kim"</code><button type="button">복사</button></div>
  <a class="ds-btn ds-btn--primary" href="/docs/install">설치 안내</a>
</section>

$ python3 style_check.py card-after.html
style: 0 error(s), 0 warning(s) in 1 file(s)
exit 0

설치

Claude Code 플러그인은 지침과 수정 직후 검사를 함께 켭니다. 나머지 방법은 검사기만 실행하므로 사람이 쓴 글과 다른 AI 도구가 만든 변경을 같은 규칙으로 검사할 때 씁니다.

Claude Code, 팀 전체

프로젝트의 .claude/settings.json에 등록하면 팀원이 레포를 열 때 플러그인이 켜집니다. 개인 설치 명령은 맨 위에 있습니다.

{
  "extraKnownMarketplaces": {
    "ai-design": { "source": { "source": "github", "repo": "jungrok5/ai-design" } }
  },
  "enabledPlugins": { "ai-design@ai-design": true }
}

복사

GitHub Action

PR이 바꾼 파일만 검사해서 보고를 PR의 변경 줄 옆에 주석으로 표시합니다. 처음에는 warn-only로 시작합니다(팀 도입).

on: pull_request
jobs:
  style:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: jungrok5/ai-design@c1e0dc94fa5bfb01e292de7bb0931dd4a2b8ca16
        with:
          warn-only: "true"

복사

pre-commit

.pre-commit-config.yaml에 추가합니다. 이 레포는 태그를 쓰지 않으므로 rev에는 CHANGELOG.md에 적힌 버전별 커밋을 씁니다. 아래 값은 1.3.0 커밋입니다.

- repo: https://github.com/jungrok5/ai-design
  rev: c1e0dc94fa5bfb01e292de7bb0931dd4a2b8ca16
  hooks:
    - id: ai-design-style

복사

명령줄

파일이나 폴더를 넘깁니다. error가 있으면 종료 코드 1, 없는 경로나 지원하지 않는 파일이 있으면 2를 돌려줍니다. 옵션은 --help로 확인합니다.

git clone --depth 1 https://github.com/jungrok5/ai-design ~/.ai-design
python3 ~/.ai-design/plugins/ai-design/style/style_check.py README.md docs

복사

Cursor, Copilot, AGENTS.md

규칙 요약과 검사 명령을 담은 파일을 각 도구의 위치에 복사합니다. 이 도구들에는 수정 직후 검사가 없으므로 pre-commit이나 GitHub Action을 함께 씁니다.

도구	파일	둘 곳
Cursor	ai-design.mdc	.cursor/rules/
GitHub Copilot	ai-design.instructions.md	.github/instructions/
AGENTS.md를 읽는 도구(Codex 등)	AGENTS.snippet.md	프로젝트 AGENTS.md에 붙여 넣기

해요체 제품, 문답집, 입문 자습서

한국어 규칙은 합니다체 문서를 기준으로 합니다. 해요체로 통일한 문서에는 ko-haeyo가 문장마다 보고되므로, 프로젝트 루트의 .style/rules.toml에서 끄고 씁니다. 문체가 섞이는지 보는 ko-register-mix는 그대로 남습니다. 문답집은 ko-question-heading, 입문 자습서는 ko-reader-talk을 같은 방법으로 끕니다.

[[rule]]
id = "ko-haeyo"
severity = "off"

공개 문서에서 측정한 결과

사람이 쓴 공개 한국어 문서 4곳(파일 1,187개, 약 21만 줄)에 1.3.0 검사기를 실행했습니다. 검사에는 모두 7.3초가 걸렸고 보고는 1,553건이었습니다. 이 측정은 사람의 글에서 무엇이 보고되는지를 보여 주며, AI가 쓴 글을 얼마나 잡는지는 알려 주지 않습니다.

규칙 23개에서 4건씩 뽑은 92건을 Claude가 문맥을 읽고 판정했습니다. 41건은 고치면 문장이 짧아지거나 정확해졌고, 44건은 규칙이 겨냥한 표현이지만 문서의 장르나 문체로 보아 그대로 둘 만했으며, 7건은 오탐이었습니다. 오탐 7건 중 6건과 측정에서 드러난 성능 문제는 1.3.0에서 고쳤습니다. 레포별 커밋, 규칙별 수, 판정 예시는 docs/measurement.md에 있습니다.

FAQ

이미 있는 문서도 한꺼번에 고쳐야 하나요?

아닙니다. 수정 직후 검사는 Claude가 방금 고친 줄만 보고합니다. GitHub Action은 PR이 바꾼 파일만 검사합니다. 나머지는 기준 파일로 기록해 두고 필요할 때 고칩니다.

시간과 토큰은 얼마나 드나요?

검사는 5 KB 파일에서 Python 시작 시간을 포함해 약 0.08초, 측정한 가장 큰 348 KB 파일에서 0.3초가 걸렸습니다. 보고가 없으면 Claude에게 아무것도 전달하지 않고, 보고가 많아도 15건까지만 전달합니다. 지침 스킬은 읽을 때 토큰이 듭니다. 위 비교의 세 작업에서 Claude Code가 보고한 비용은 ai-design을 켰을 때 1.4–2.0배였습니다.

코드 작업에도 끼어드나요?

수정 직후 검사는 Markdown, HTML, CSS, JSX/TSX, Vue, Svelte, Astro 파일만 보고 .py, .ts 같은 파일은 출력 없이 넘어갑니다. 지침 스킬은 설명문을 보고 Claude가 문서나 화면 작업에서만 고르며, 코드 버그 수정에서 고르지 않는지 확인하는 평가 케이스를 evals/에 두었습니다.

AI가 쓴 글인지 판별하나요?

판별하지 않습니다. 표현을 찾는 문체 검사기이므로 사람이 쓴 문서에서도 번역투나 군더더기 표현을 보고합니다(측정).

영어 문서에도 쓸 수 있나요?

쓸 수 있지만 영어 규칙은 14개로 한국어 34개보다 적습니다. 화면 코드 규칙 20개는 언어와 상관없이 적용됩니다.

한계

• 정규식이라 문맥을 모릅니다. 자연스러운 경우가 많은 규칙은 warning으로 두었습니다. 일부는 한 파일에 여러 번 나올 때만 보고합니다(max_per_file).
• 문장 단위로만 검사합니다. 섹션 반복이나 같은 사실의 중복 같은 페이지 구성은 지침 스킬에만 적혀 있습니다.
• 사용 전후 비교는 작업마다 한 번씩 실행한 결과입니다. 같은 요청도 실행할 때마다 결과가 달라집니다. 비교 뒤에 그 결과에서 본 표현을 잡는 규칙 4개(ko-question-heading, ko-slogan, ko-cta-now, ui-default-accent)를 추가했으므로, 비교에 붙은 검사 결과는 독립적인 근거가 아닙니다.

규칙은 한국어 34개, 영어 14개, 언어 공통 2개, 화면 코드 20개로 모두 70개이고, 목록은 style_check.py --list-rules로 확인합니다.