agent-style

당신의 AI 에이전트가 기술 전문가처럼 글을 쓰게 만드세요.

21가지 규칙: 고전 작법 가이드에서 추출한 12가지, 2022-2026년 LLM 출력에 대한 현장 관찰을 통해 얻은 9가지 규칙.

맨 윗줄은 정체성(identity)을 나타냅니다: 21가지 규칙 중 12가지는 정전(canonical)이며 9가지는 현장에서 관찰된 것입니다. 빨간색 테두리는 두 가지 핵심 규칙(RULE-01 지식의 저주(curse-of-knowledge) 및 RULE-H 인용 규율(citation discipline))을 표시합니다. 하단의 세 줄은 메커니즘을 나타내며, 각각 실제 v0.3.0 벤치마크 초안 쌍(동일한 프롬프트, 규칙 세트 적용 여부에 따른 독립적 생성 결과)에서 추출되었습니다: Gemini 3 Flash의 제품 설명(위반 사항 8건 → 0건), Claude Opus 4.7의 설계 문서(design-doc) 섹션(14건 → 7건), 그리고 Gemini 3 Flash의 논문 관련 연구(related-work) 섹션(6건 → 4건)입니다. (원본 초안은 세 가지 프롬프트 명칭 벤치마크(AgentBench, BFCL, tau-bench)에 고정되어 있어, agent-style review에 의해 측정된 스타일 변화량은 허위 인용 소음으로부터 격리됩니다. 다만, 패널을 세 문장으로 유지하기 위해 표시된 베이스라인 스니펫은 세 번째 이름 직전에서 끊깁니다.) 각 행은 왼쪽에 규칙을 위반한 구절이 강조된 AI 초안을, 가운데에는 적용된 특정 규칙을, 오른쪽에는 동일한 길이 제한, 동일한 어조(register), 동일한 문서 유형을 유지하며 수정된 버전을 보여줍니다.

사후 린터(post-hoc linter)로서가 아니라, AI 코딩 및 글쓰기 에이전트가 **생성 시점(generation time)**에 따를 수 있도록 구성된 선별된 영어 작법 규칙 세트입니다.

범위 내 (In scope)	범위 외 (Out of scope)
API 문서, 설계 문서(design docs), 연구 논문, 연구 제안서	소설, 시, 마케팅 문구
...

21가지 규칙은 출처에 따라 나뉩니다. 에이전트는 두 그룹을 동등한 동료로 읽으며, 어떤 그룹도 다른 그룹보다 우선순위가 높다고 주석이 달리지 않습니다.

Strunk & White, Orwell, Pinker, 그리고 Gopen & Swan의 저서에서 추출되었습니다. 각 규칙은 장(chapter), 절(section) 또는 에세이 규칙을 통해 출처를 인용하며, 저는 모든 인용을 원전과 대조하여 검증했습니다. 아래 표에는 전체 이름이 포함되어 있습니다. RULE-01..12

(정전 (canonical)). 수십 개의 글쓰기 프로젝트(논문, 연구 제안서, 기술 문서, 에이전트 설정) 및 코드 출시 과정에서 2022년부터 2026년까지 AI 출력물로부터 기록한 패턴들입니다. 투명한 출처 표기: 이들은 문헌에 근거한 것이 아니라, 정전 세트만으로는 놓칠 수 있는 LLM 특유의 실패 모드 (failure modes)를 포착한 것입니다 (RULE-H 인용 규율이 가장 중요합니다). 아래 표에 전체 이름이 포함되어 있습니다. RULE-A..I

(현장 관찰 (field-observed)).

네 가지 정전 소스 중 하나인 Strunk & White의 The Elements of Style (1918/1959)에 경의를 표하며 명명되었습니다.

글쓰기 권위자들로부터 출처를 가져왔으며, 각 규칙은 장(chapter), 절(section) 또는 에세이 규칙을 통해 출처를 인용합니다.

#	규칙	주요 출처
01	독자가 당신의 암묵적 지식을 공유한다고 가정하지 마십시오	Pinker 2014, Ch. 3
...

2022년부터 2026년까지 연구, 제안서, 문서화 및 에이전트 설정 작업 전반에서 LLM 출력물로부터 기록된 구조적 패턴입니다. 에이전트가 규칙 세트를 소비할 때 정전 규칙과 동등한 피어 입력 (peer input)으로 취급됩니다.

#	규칙
A	내용이 진정한 목록인 경우가 아니라면 산문을 글머리 기호(bullet points)로 변환하지 마십시오 (또한 2개 항목이거나 문장으로 적합한 경우 글머리 기호를 과도하게 사용하지 마십시오)
...

탈출구 (Escape hatch) (Orwell 1946 Rule 6): "명백히 야만적인 말을 하는 것보다 차라리 이 규칙 중 어느 하나라도 먼저 어기는 것이 낫다." 규칙은 명확성을 위한 가이드일 뿐, 그 자체가 목적은 아닙니다.

BAD/GOOD 예시, 강제 등급(enforcement tier) 및 근거(rationale)가 포함된 규칙별 전체 블록은 RULES.md를 참조하십시오.

10개의 고정된 산문 작업(PR 설명 2개, 디자인 문서 섹션 1개, 커밋 메시지 1개, 논문 섹션 4개, 제품 설명 1개, NSF 스타일의 구체적 목표 1개)에 대한 건전성 벤치마크(Sanity bench)를 수행하였으며, 각 조건당 2회 생성하였고, 생성 시점에 agent-style을 로드한 플래그십 모델 초안 작성과 로드하지 않은 경우를 비교했습니다. 세 가지 모델이 표시됩니다: Claude Opus 4.7은 45% 감소 (105 → 58건의 위반); Codex CLI를 통한 OpenAI GPT-5.4는 45% 감소 (51 → 28건); Gemini 3 Flash는 82% 감소 (79 → 14건). GitHub Copilot CLI 러너도 테스트되었으나, -p 옵션 때문에 그림에서는 제외되었습니다.

프로그래매틱 모드(programmatic mode)는 지침 파일(instruction files)을 로드하지 않습니다 (+3% 노이즈 발생; CHANGELOG.md 참고). 4개의 모든 러너(runner)에 대한 전체 스코어카드와 각 러너별 초안은 docs/bench-0.3.0.md 및 docs/bench-0.3.0-drafts/에서 확인할 수 있으며, 재현 단계는 RELEASING.md의 "Bench (Local Only)" 섹션을 참조하십시오.

수치는 방향성을 나타내는 지표이며, 통계적으로 유의미한(statsig) 수치는 아닙니다: 10개 작업 × 2번의 생성 × 2가지 조건 = 러너당 40회 호출. 핵심 요점은, 지침 파일이 모델의 컨텍스트(context)에 실제로 도달하는 모든 프런티어 모델 제품군(frontier family)에서 이 규칙 세트가 기계적인 AI 특징(AI-tell) 밀도를 감소시킨다는 것입니다. 감소 폭의 정확한 크기는 각 모델의 베이스라인(baseline)에 따라 다릅니다(기본적으로 긴 문장이나 엠 대시(em-dash)를 더 많이 생성하는 모델에서 더 크게 나타나며, 이미 깔끔한 모델에서는 작거나 없을 수 있습니다).

AI 코딩 및 글쓰기 에이전트(agents): Claude Code, Codex, GitHub Copilot, Cursor, Aider, Anthropic Skills, Kiro, Replit Agent, Windsurf, Amazon Q Developer, JetBrains AI Assistant, Ollama, Continue.dev, Tabnine, OpenCode, OpenAI Agents SDK skills, 그리고 AGENTS.md를 준수하는 모든 도구. 각 에이전트는 시스템 프롬프트(system prompt) 또는 프로젝트 설정(project config)의 일부로 이 규칙 세트를 읽습니다. 해당 에이전트 설정의 유지 관리자(Maintainers) 중 생성된 산문이 일반적인 LLM 특징 패턴(tell-patterns)을 재현하는 대신 문헌에 기반한 글쓰기 관습을 따르기를 원하는 경우에 적합합니다.

AI 에이전트의 출력물에 규칙을 적용하는 두 가지 방법이 있습니다. 일반적으로 두 가지를 모두 사용합니다:

1. 소프트 강제 적용(Soft enforcement)(기본값): 규칙이 생성 시점에 로드되므로, 에이전트는 첫 번째 초안을 작성하는 동안 규칙을 따르려고 시도합니다. 도구당 하나의 enable 명령어를 사용하면, 에이전트가 agent-style의 21가지 규칙을 컨텍스트의 일부로 읽습니다.
2. 스킬(Skill)(선택적 2차 작업): 초안이 작성된 후 리뷰를 요청합니다. style-review는 동일한 21가지 규칙을 기준으로 초안을 감사(audit)하며, 사용자의 확인을 거쳐 원본 옆에 다듬어진 복사본을 작성합니다. 사용자의 소스 파일은 절대 수정되지 않습니다.

CLI를 한 번 설치한 후, 원하는 경로를 선택하십시오.

pip install agent-style # Python 사용자
# 또는: npm install -g agent-style # Node 사용자
# 또는: npx --yes agent-style@0.3.5 <subcommand> # 설치 불필요

AI 에이전트(AI Agent)를 통한 설정

CLI가 설치되었다면 (위의 설치 블록 참고), 아래 블록을 AI 에이전트에 붙여넣으십시오. 에이전트가 적절한 어댑터(adapter)를 선택하고, enable을 실행하며, 검증을 수행하고, 호스트가 스킬(skills)을 지원하는 경우 style-review를 제안합니다. 쉘 명령(shell commands)을 실행할 수 있는 모든 AI 에이전트와 함께 작동합니다: Claude Code, Codex, Cursor, Aider, Kiro, GitHub Copilot 등.

이 프로젝트에 agent-style을 설정합니다. 단계:
(만약 `agent-style`이 PATH에 없다면, 아래 모든 명령의 `agent-style`을 `npx --yes agent-style`로 대체하십시오.)
...

또는 직접 실행하십시오:

agent-style enable claude-code # Claude Code 연결
# Claude Code 세션 내부에서, 이제 당신의 산문(prose)은 agent-style의 21가지 규칙을 따릅니다.

다른 도구들도 동일한 방식으로 작동합니다 — 도구 이름을 교체하십시오:

agent-style list-tools # 지원되는 모든 도구 확인
agent-style enable agents-md # Codex, Jules, Zed, Warp, Gemini CLI, VS Code 및 기타
agent-style enable cursor # Cursor
...

주의 사항: 소프트 인포스먼트(soft enforcement)는 모델에게 *넛지(nudges, 슬쩍 권유)*를 주는 방식입니다. 학습 데이터에 우선순위가 높은 어휘인 leverages, cutting-edge, Additionally로 시작하는 문장, 그리고 맺음말 문장들은 특히 200단어 이상의 산문의 경우 첫 번째 초안에 여전히 나타날 수 있습니다. 이것이 경로 2(path 2)가 존재하는 이유입니다.

도구별 enable 동작 (모두 안전하며, 모두 멱등적임/Idempotent)

enable 동작 (모두 안전하며, 모두 멱등적임/Idempotent)

Claude Code (import-marker 작성): 기존의 CLAUDE.md 파일에 마커 블록 형태로 @.agent-style/claude-code.md를 안전하게 추가(safe-appends)합니다. CLAUDE.md가 없는 경우에만 생성합니다. agent-style/RULES.md 및 .agent-style/claude-code.md를 생성합니다.

AGENTS.md, Copilot 저장소 전체 (append-block): 기존의 지침 파일(instruction file)에 마커로 감싸진 압축된 어댑터 블록을 안전하게 추가(safe-appends)합니다. 마커 위아래의 콘텐츠는 보존됩니다.

)"Cursor, Copilot path-scoped, Anthropic Skills (: 툴의 규칙 디렉토리 경로(rule-directory path)에 새로운 에이전트 스타일 소유 파일(agent-style-owned file)을 작성합니다 (owned-file)

.cursor/rules/agent-style.mdc

,.github/instructions/agent-style.instructions.md`

,.claude/skills/agent-style/SKILL.md`

). 만약 에이전트 스타일이 아닌 파일이 이미 존재한다면 실패(Fails closed)합니다.

Codex API (: print-only 방식으로 작성합니다)

.agent-style/codex-system-prompt.md

; 프롬프트 본문은 표준 출력(stdout)으로, 수동 단계(manual-step) 지침은 표준 에러(stderr)로 출력합니다. 출력된 프롬프트를 Codex API의 system_prompt에 붙여넣으세요.

Aider (: multi-file-required 방식으로 작성합니다)

.agent-style/aider-conventions.md

; .aider.conf.yml 스니펫을 표준 에러(stderr)로 출력합니다. 두 파일을 모두 설정(config)에 붙여넣으세요.

Kiro (: 자동 포함되는 스티어링 파일(steering file)로서 owned-file 방식으로 작성합니다)

.kiro/steering/agent-style.md

. Kiro는 워크스페이스 내의 모든 상호작용을 위해 세션 시작 시 이 파일을 로드합니다.

print-only 및 multi-file-required 방식의 경우, JSON 출력에는 manual_step_required: true 및 enabled: false가 포함됩니다. 종료 코드(exit code)는 0을 유지하며(CLI가 할 수 있는 모든 작업을 수행했음을 의미), 사용자 출력의 첫 번째 줄은 정확히 manual step required: 뒤에 특정 작업 내용이 뒤따릅니다.

표면별 설치 표 (v0.3.5 기본 세트)

표면별 설치 표 (v0.3.5 기본 세트)

Tool	install_mode	Target path
Claude Code	import-marker	CLAUDE.md (마커 블록에 @.agent-style/claude-code.md 포함)
AGENTS.md (Codex, Jules, Zed, Warp, Gemini CLI, VS Code 등)	append-block	리포지토리 루트의 AGENTS.md
GitHub Copilot (리포지토리 전체)	append-block	.github/copilot-instructions.md
GitHub Copilot (경로 한정)	owned-file	.github/instructions/agent-style.instructions.md
Cursor	owned-file	.cursor/rules/agent-style.mdc
Anthropic Skills	owned-file	.claude/skills/agent-style/SKILL.md
Codex (API / 수동 붙여넣기)	print-only	.agent-style/codex-system-prompt.md (사용자가 API 시스템 프롬프트에 붙여넣음)
Aider	multi-file-required	.agent-style/aider-conventions.md + .aider.conf.yml 스니펫
Kiro (AWS IDE)	owned-file	.kiro/steering/agent-style.md
style-review (skill)	skill-with-references	.claude/skills/style-review/SKILL.md + .agent-style/skills/style-review/references/

Amazon Q Developer, JetBrains AI Assistant, Windsurf, Ollama, Replit, OpenCode, Continue.dev, Tabnine, OpenAI Agents SDK skills, 그리고 위 목록을 초과하는 Copilot 경로 한정 변형은 v1.1에 계획되어 있습니다. adapter-matrix.md의 "Planned adapters" 섹션을 참조하십시오.

.

설치 불필요한 경로: 고정된 curl

레시피

curl

레시피패키지 설치를 건너뛰고, 어댑터와 RULES.md에 고정합니다.

일관성을 유지하려면:

AGENT_STYLE_REF=v0.3.5
mkdir -p .agent-style
curl -fsSLo .agent-style/RULES.md "https://raw.githubusercontent.com/yzhao062/agent-style/${AGENT_STYLE_REF}/RULES.md"
...

그런 다음 CLAUDE.md에 한 줄을 추가합니다.

(파일이 없을 경우에만 생성하고, 절대 덮어쓰지 마십시오):

@.agent-style/claude-code.md

다른 표면의 경우 어댑터 파일 이름을 대체하십시오. curl 명령어는 .agent-style/ 아래에만 작성합니다. 한 줄 임포트는 사용자가 소유한 파일에 수정하는 유일한 편집입니다.

호스트가 skill 기능을 지원하는지에 따라 두 가지 방법으로 사용할 수 있습니다:

# Skill-host 경로 (Claude Code / Anthropic Skills): 한 번 설치 후, /style-review <file> 실행
agent-style enable style-review # 활성화된 skill 지원 인터페이스를 자동 감지합니다
# Claude Code 내부에서:
...

/style-review DESIGN.md 실행 시 발생하는 일 (skill 경로):

• 21개 모든 규칙에 대해 해당 파일에 대한 결정론적 감사 (Deterministic audit)를 수행합니다.
• Skill이 다음과 같이 질문합니다:
  *"DESIGN.reviewed.md에 다듬어진 초안을 생성할까요?"
• '예'를 선택하면: 원본 파일 옆에 수정된 복사본을 작성하고 차이점(diff)을 보여줍니다.
  원본 파일은 절대 수정되지 않습니다.

agent-style review DESIGN.md 실행 시 얻는 결과 (CLI 경로): 동일한 결정론적 감사 — em-dash, 전문 용어 (jargon), 전환어 (transition openers), 상투적 표현 (clichés), 축약형 (contractions), 문장 길이, 불렛 포인트 과다 사용, 동일 단어 시작, 단락 종결어에 대한 기계적 + 구조적 탐지기를 사용합니다. 의미론적 규칙 (모호한 주장, 근거 없는 주장 등)은 다음과 같이 반환됩니다:

status: "skipped"

이는 해당 규칙들이 skill host의 모델을 필요로 하기 때문입니다. 일반 CLI에서는 다듬기(polish) 기능이 제공되지 않습니다. Claude Opus 4.7 및 OpenAI GPT-5.4에서 측정된 기계적 위반 사항 감소 수치는 위의 'Does It Work?' 섹션을 참조하십시오.

상세 Skill 워크플로 (SKILL.md가 Claude Code에 지시하는 내용)

• 결정론적 감사를 위해 (CLI 경로와 동일한 JSON 사용) agent-style review --audit-only DESIGN.md를 셸(Shell)로 호출합니다.
• 문맥 인지 추론 (context-aware reasoning)이 필요한 7가지 규칙에 대해 host 모델을 통한 의미론적 판단을 추가합니다: RULE-01 지식의 저주 (curse of knowledge), RULE-03 모호한 언어 (vague language), RULE-04 불필요한 단어 (needless words), RULE-08 조정되지 않은 주장 (uncalibrated claims), RULE-11 강조 위치 (stress position), RULE-F 용어 드리프트 (term drift), RULE-H 인용 규율 (citation discipline).
• 결정론적 점수와 의미론적 점수를 병합하여 규칙별 횟수와 각 규칙의 상위 5개 위반 사항을 보고합니다.
• 사용자에게 질문합니다:
  *"DESIGN.reviewed.md에 다듬어진 초안을 생성할까요?"
• '예'를 선택하면, references/revision-prompt.md를 사용하여 수정 프롬프트 (revision prompt)를 작성합니다.