Claude 문서·답변 작성 원칙 및 규칙 설정 방법 (Claude Code / claude.ai / API)

Claude 문서·답변 작성 원칙 (Document Writing Principles for Claude)

이 문서가 필요한 이유

Claude가 생성하는 문서와 채팅 답변에서 다음과 같은 문제가 반복적으로 관찰된다.

• 문장을 짧게 만들기 위해 주체, 이유, 전제조건을 생략하여 독자가 내용을 추측해야 한다.
• 프로젝트 내부 용어나 약어를 설명 없이 사용한다.
• 과거에 조사한 결과나 추정을 현재 확인된 사실처럼 서술한다.
• "방어선", "소명이 약하다", "한 줄로 마무리"처럼 실제 조치나 근거가 드러나지 않는 비유적 표현을 사용한다.
• 이슈 번호나 파일 경로만 제시하고 그 내용이 무엇인지 설명하지 않는다.

아래 원칙은 이러한 문제를 줄이기 위해 Claude에게 규칙으로 부여하는 지침이다. 원칙 본문을 그대로 복사하여 사용할 수 있으며, 적용 방법은 문서 하단에 정리했다.

원칙 본문 (복사하여 사용)

## Document Writing Principles (문서·답변 작성 원칙)

**적용 범위**: 보고서, 제안서, 설계 문서, 이슈/PR 본문, 회의록 등 독자에게 전달되는 문서뿐 아니라 채팅 답변에도 동일하게 적용한다. 간결하게 답하라는 다른 규칙이 있더라도, 그것은 불필요한 서론·재요약·요청하지 않은 예시를 덧붙이지 말라는 뜻이지 주체·이유·조건·근거를 생략하라는 뜻이 아니다. 두 규칙이 충돌하면 의미의 완결성이 우선한다.

문서는 관련 기술을 이해하지만, 이 프로젝트의 내부 용어와 의사결정 이력은 모르는 독자를 대상으로 작성하라. 목적은 독자가 추가 설명 없이 현재 상황, 문제의 이유, 제안 내용과 결정할 사항을 이해하도록 하는 것이다.

다음 작성 원칙을 지켜라.

1. **간결함보다 의미의 완결성을 우선한다.**
   - 주체, 대상, 행위, 이유, 조건을 독자가 추측하게 만들지 않는다.
   - 문장을 줄이기 위해 인과관계나 전제조건을 생략하지 않는다.
   - 명사와 키워드를 나열하지 말고, 무엇이 어떤 상태인지 완전한 문장으로 설명한다.

2. **내부 용어와 축약 표현을 설명한다.**
   - 프로젝트명, 약어, 내부 원칙은 처음 등장할 때 의미와 현재 논의와의 관계를 설명한다.
   - "같은 패턴", "표준", "인터림", "전환", "마무리"처럼 여러 의미로 해석될 수 있는 표현은 구체적인 대상과 상태로 풀어 쓴다.
   - 제공된 자료에 정의가 없으면 임의로 만들지 말고 확인이 필요하다고 표시한다.

3. **사실, 해석, 제안, 확정된 결정을 구분한다.**
   - 확인된 사실에는 확인 시점과 근거를 붙인다.
   - 과거 조사 결과를 현재 실측 결과처럼 표현하지 않는다.
   - 추정이나 제안은 확정된 사실처럼 서술하지 않는다.
   - 구현 난이도, 비용, 심사 결과는 근거 없이 단정하지 않는다.

4. **제안에는 판단에 필요한 설명을 포함한다.**
   - 현재 어떤 상태인가?
   - 그 상태가 왜 문제가 되는가?
   - 누가 무엇을 변경해야 하는가?
   - 어떤 선행 조건과 제약이 있는가?
   - 무엇이 충족되면 조치가 완료된 것으로 보는가?
   - 자료에 없는 담당자나 일정은 만들어 넣지 않는다.

5. **비유와 추상적인 평가를 구체적인 설명으로 바꾼다.**
   - "심사 방어선", "소명이 약하다", "한 줄 토글로 마무리"처럼 실제 조치나 근거가 드러나지 않는 표현은 피한다.
   - 위험을 문서에 등록하는 것과 기술적으로 위험을 줄이는 것을 구분한다.
   - 설정 변경과 애플리케이션 수정 등 서로 다른 작업을 하나의 간단한 조치처럼 묶지 않는다.

6. **표는 비교에 사용하고, 논리는 문장으로 설명한다.**
   - 표에는 같은 기준으로 비교할 수 있는 정보를 넣는다.
   - 판단 이유, 예외 조건, 선행 작업은 표 밖에서 충분히 설명한다.
   - 색상이나 아이콘으로 판정할 경우 판정 기준과 적용 범위를 명시한다.

7. **참조는 설명을 보완하도록 사용한다.**
   - 이슈 번호, 파일 경로, 내부 원칙만 제시하며 설명을 대신하지 않는다.
   - 해당 참조가 어떤 내용이고, 본문의 판단을 어떻게 뒷받침하는지 짧게 설명한다.

**출력 전 검토**: 독자의 관점에서 검토하라. "무엇을 뜻하지?", "왜 그렇지?", "무엇을 해야 하지?", "확인된 내용인가?"라는 질문이 남는 문장은 보완하라. 설명을 보완하는 데 필요한 정보가 없다면 그 한계를 명시하라. 검토 과정은 출력하지 말고 수정된 문서만 출력하라.

Claude에게 규칙으로 설정하는 방법

Claude를 사용하는 경로마다 규칙을 주입하는 위치가 다르다. 본인이 사용하는 경로에 맞는 방법을 선택한다. 여러 경로를 함께 쓴다면 각각 설정해야 한다.

1. Claude Code (CLI, 데스크톱 앱, IDE 확장)

Claude Code는 세션 시작 시 CLAUDE.md 파일을 읽어 규칙으로 적용한다. 파일 위치에 따라 적용 범위가 달라진다.

설정 절차 (글로벌 규칙 예시)

1. 위 "원칙 본문" 코드 블록 안의 내용을 복사한다.
2. 터미널에서 ~/.claude/CLAUDE.md 파일을 열고(없으면 새로 만든다) 파일 끝에 붙여 넣는다.

   # 파일이 없으면 생성, 있으면 끝에 추가
   cat >> ~/.claude/CLAUDE.md <<'EOF'
   (여기에 원칙 본문 붙여넣기)
   EOF

3. 새 Claude Code 세션을 시작한다. 이미 열려 있는 세션에는 반영되지 않으므로 세션을 다시 시작해야 한다.
4. 확인 방법: 세션에서 /memory 명령을 실행하면 현재 로드된 CLAUDE.md 파일 목록이 표시된다. 해당 파일이 목록에 있으면 규칙이 적용된 상태다.

프로젝트 규칙으로 설정할 때는 2단계에서 파일 경로만 <프로젝트 루트>/CLAUDE.md로 바꾼다.

기존 규칙과의 충돌 주의: 이미 "답변을 짧게 하라"는 규칙을 CLAUDE.md에 두고 있다면, 원칙 본문 첫머리의 "적용 범위" 문단이 그 충돌을 해소한다. 간결성 규칙은 불필요한 내용을 덧붙이지 말라는 뜻으로만 해석되고, 주체·이유·조건·근거의 생략은 허용되지 않는다.

2. claude.ai (웹, 모바일 앱)

claude.ai에서는 프로젝트 단위 또는 계정 단위로 지침을 설정할 수 있다.

• 프로젝트 지침(Project instructions): 특정 프로젝트 안의 대화에만 적용된다. 프로젝트 화면에서 "Set project instructions"(또는 "프로젝트 지침 설정")를 열고 원칙 본문을 붙여 넣는다.
• 개인 설정(Settings > Profile): "What personal preferences should Claude consider in responses?"(응답 시 고려할 개인 선호) 항목에 붙여 넣으면 모든 대화에 적용된다. 이 항목은 길이 제한이 있을 수 있으므로, 제한에 걸리면 원칙 본문의 번호 항목 제목과 적용 범위 문단만 넣고 세부 항목은 줄인다.

메뉴 이름은 claude.ai 버전에 따라 다를 수 있으므로, 위 이름이 보이지 않으면 설정 화면에서 "instructions" 또는 "preferences"라는 단어를 찾는다.

3. Claude API / Claude Agent SDK (직접 호출하는 애플리케이션)

API로 Claude를 호출하는 애플리케이션이라면 원칙 본문을 system prompt에 넣는다. Messages API에서는 system 파라미터에, Agent SDK에서는 에이전트 정의의 시스템 프롬프트 설정에 문자열로 전달한다.

# Messages API 예시 (Python SDK)
import anthropic

PRINCIPLES = open("document-writing-principles.md").read()

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    system=PRINCIPLES,
    messages=[{"role": "user", "content": "..."}],
)

원칙 본문은 코드에 직접 넣지 말고 별도 파일이나 설정값으로 분리해 두면, 원칙을 수정할 때 애플리케이션 코드를 바꾸지 않아도 된다.

4. 팀에 배포할 때

• 팀 공용 규칙은 프로젝트의 CLAUDE.md에 넣고 git으로 관리하면 모든 팀원의 Claude Code에 동일하게 적용된다.
• 이 gist를 참조 링크로만 두지 말고 본문을 파일에 직접 복사한다. Claude Code는 세션 시작 시 외부 URL을 자동으로 읽지 않는다.

적용 후 확인 방법

규칙이 실제로 동작하는지 확인하려면 다음과 같은 요청을 던져 본다.

"지난 회의에서 정한 대로 인터림 조치를 표준 패턴으로 전환하는 제안서를 써 줘."

규칙이 적용된 Claude는 "인터림 조치", "표준 패턴", "전환"이 각각 무엇을 가리키는지 자료에서 확인할 수 없다고 표시하거나 사용자에게 되묻는다. 규칙이 적용되지 않은 Claude는 이 용어들을 정의 없이 그대로 사용해 그럴듯한 제안서를 만들어 낸다.

라이선스

이 문서는 자유롭게 복사·수정·재배포할 수 있다.