Opus 5.5에서 CLAUDE.md를 검토하는 데 어려움을 느끼는 분들을 위해, 그 이유와 활용 가능한 프롬프트 4가지를 정리했습니다.
노력(사고 깊이 설정)을 높이 설정했는데도 불구하고, 답이 얕은 느낌이 드네요. Opus 5.5로 교체 이후, 이러한 어색함이 느껴지시나요.
결론부터 말씀드리겠습니다. Opus 5.5로 교체한 후에는 Claude.md와 스킬을 한 번쯤 살펴보시는 것이 좋습니다. 이전 모델에 맞춰 작성했던 지시나 설정이 그대로 적용되지 않거나, 과도하게 적용될 수 있기 때문입니다.
재검토는 Claude Code를 활용하면 1줄씩 직접 읽지 않아도 진행할 수 있습니다. 이 글에서는 재검토가 필요한 이유와 그대로 사용할 수 있는 프로ンプ트 4개를 제공합니다.
이 글은 Claude Code를 시작하는 분들을 위해 작성되었습니다. 먼저 용어를 통일하겠습니다.
- CLAUDE.md (클로드 코드는 세션을 시작할 때마다 읽는 프로젝트 설명서)
- 기술(정해진 작업 절차를 요약한 파일. 내용은 SKILL.md)
- 사브 에이전트(일부 업무를 위탁하는 별도의 Claude. 정의 파일은 .claude/agents/ 폴더에 보관)
Claude Code를 사용하여 Opus 5.5를 사용하려면 v2.1.280 이상이 필요합니다. 터미널에서 `claude --version` 명령어를 입력하여 확인하고, 버전이 낮으면 `claude update` 명령어를 통해 업데이트하세요.
보정하지 않으면 이런 일이 발생할 수 있다
보정하지 않고 계속 사용하면 다음과 같은 일이 발생할 수 있습니다. 모두 오류는 발생하지 않습니다.
- 설정했던 노력이 제대로 적용되지 않고 있습니다.
- 지지난 지시가 여전히 유효하게 작용하고 있다.
- 두 개 지점에 설치된 스킬 버전이 달라, 결정한 규칙이 빠져 있다.
두 번째와 세 번째는 제가 2026년 9월 26일에 실제로 찾은 것입니다. 서브에이전트 정의 파일에는 “9월 7일까지는 ~를 제안하지 않는다”는 지시 사항이 9월 26일에도 남아 있었습니다. 스킬 버전의 차이는 다음 장에서 다룹니다.
왜 Opus 5.5에서 검토가 필요한가요?
이유는 세 가지입니다. 이전 모델에 대한 지시사항이 더 이상 필요 없기 때문, 설정의 기본값이 변경되었기 때문, 그리고 파일을 방치하면 오래되기 때문입니다.
이전 모델을 위한 지침이 더 이상 유효하지 않습니다.
오пус 5.5의 이관 가이드에는 다음과 같은 문구가 있습니다. 오пус 5에 맞게 조정된 지침은 더 이상 필요하지 않을 수 있습니다.
예를 들어 “답변하기 전에 잘 생각하세요”와 같은 지시입니다. Opus 5.5에서는 생각 기능이 항상 활성화되어 있습니다. Opus 5.5를 위한 프롬프트 안내에는 이러한 지시를 무시하는 것을 고려해 볼 수 있다고 제시합니다. 챗봇 지시문 안내에 대해서도 마찬가지입니다. CLAUDE.md에도 동일한 관점이 사용됩니다.
하지만 클로드 코드의 울트라틴크는 예외입니다. 그 턴에만 깊이 생각하도록, 공식적으로 준비된 키워드는 그대로 남깁니다.
반드시, 절대로, “CRITICAL”과 같은 강한 표현들도 검토 대상입니다. Anthropic의 문서는 Opus 4.5와 4.6과 같은 이전 버전의 모델에 대해 다루고 있습니다. 강한 표현은 도구나 기술의 과도한 사용를 유발할 수 있습니다. “CRITICAL: You MUST use this tool when...”는 “Use this tool when...”로 충분합니다. Opus 5.5에 대해서는 같은 언급을 찾을 수 없었지만, 제 테스트 결과에서 강한 표현을 줄여도 어려움이 없었습니다.
설정 기본값이 변경되었습니다.
Claude Code에서 Opus 5.5의 기본 설정은 미디엄입니다. Opus 5는 하이였습니다. Anthropic의 시험 결과, Opus 5의 하이와 동등하거나 더 우수한 평가를 받았습니다. 이는 코딩 및 지식 기반 업무 평가 결과입니다.
주의할 점은 이전 저장했던 설정입니다. 사용자 설정 파일(~/.claude/settings.json)에 직접 쓴 `effortLevel`은 Opus 5.5에는 영향을 미치지 않습니다. 현재의 `effort`는 모델마다 저장하는 방식으로, 이전 방식은 새로운 모델에 이월되지 않기 때문입니다. 여기에만 작성하는 경우, `/effort` 또는 `/model`로 선택을 변경할 때까지 기본 설정으로 작동합니다. “high로 설정했はず”가 작동하지 않는 이유는 여기에 있을 가능성이 있습니다. `/effort`로 선택을 변경하면 문제가 해결됩니다.
지시 파일은 방치하면 낡습니다.
지시 파일은 작성일의 상황과 숫자까지 그대로 보존됩니다. 날짜가 기재된 지시사항이나 해당 시점의 숫자가 그 예입니다.
같은 기술을 2군데에 두고 있는 경우에는 버전 차이에도 주의가 필요합니다. 저는 손안의 프로젝트와 claude.ai의 2군데에 두고 있었습니다(claude.ai에도 기술을 등록할 수 있습니다). 비교하면 내용까지 같은 파일은 단 2개였습니다. claude.ai 측에서 기술을 짧게 수정했을 때, 오래된 버전을 바탕으로 한 문제였습니다.
하지만, 지나치게 자르면 부러집니다.
검토는 단순히 삭제하는 것만이 아닙니다. 저는 Claude.AI 측의 짧은 버전과 원본 버전을 비교했습니다. 같은 요청을 3회씩 내었을 때, 짧은 버전에서는 3회 모두 기사의 서두 장이 나오지 않았고, 원본 버전에서는 3회 모두 나타났습니다.
오류는 발생하지 않았고, 출력은 그럴듯하게 정리되어 있어서 읽기에만 집중하면 알아차리지 못했습니다. 깜짝 놀랐습니다. 짧은 버전에는 해당 장을 배치하는 칸 자체가 없었던 것입니다.
레시피를 기준으로 설명드리겠습니다. 요리사가 실력이 뛰어난 사람에게 대체되었다면 “절대적으로”, “반드시”라는 강조 표시(붉은색 밑줄)는 지워도 됩니다. 하지만 코스 요리 메뉴에서 전채 요리의 접시를 삭제했다면, 아무리 요리 실력이 뛰어나도 전채 요리는 나오지 않습니다. 강조 표시(강조 문구)가 강한 표현으로, 해당 항목(장, 표, 체크 항목)을 나타냅니다.
검토에 활용하는 프롬프트 4가지
진행 방법은 4단락입니다. ① 목록을 작성하고 기록을 보관합니다. ② 검토합니다. ③ 수정 방안을 제시하도록 합니다. ④ 앞뒤 내용을 비교하여 확인합니다. 모두 Claude Code의 채팅란에 그대로 붙여넣을 수 있습니다. 〈〉 안의 부분만 자신의 환경에 맞게 수정해 주세요. 프롬프트 1~3은 같은 대화 안에서 계속해서 붙여넣습니다. 이전 결과를 사용하기 때문입니다.
프롬프트 1: 목록을 작성하고 관련 증거를 수집하십시오.
먼저 수정 대상 전체를 기록하고, 수정 전 원본을 보관합니다.
〈控え의 보관 위치〉는 프로젝트 외부로 옮깁니다(예: /Documents). 프로젝트 내부나 .claude의 안에 두면, 控え의 CLAUDE.md나 스킬까지 읽힐 수 있습니다. git을 사용하는 경우에도 控え를 가져옵니다. /.claude 쪽에 있는 파일은 프로젝트의 git에 포함되지 않는 경우가 많습니다.
클로드 AI에 자신의 기술을 등록할 때, 등록에 사용한 우편번호를 보관해 둡니다. 직접 수정하면 클로드 AI 측에서도 다시 등록합니다.
다음 두 사항을 검토합니다.
클루드 코드 v2.1.283 이후 버전부터는 채팅창에 `/doctor prompt-audit`를 입력하는 것이 가장 빠릅니다. CLAUDE.md, 스킬, 서브 에이전트 정의에서 이전 모델에 맞는 방법을 찾아주고, 발견한 내용과 수정 제안을 제시하며 확인 없이 파일을 수정하지 않습니다. `/doctor`의 제안을 그대로 사용한다면 프롬프트 4로, 방향을 수정하고 싶다면 프롬프트 3로 진행합니다.
사용할 수 없는 환경이나, 스스로 시점을 지정하고 싶을 때는 다음 프롬프트를 사용합니다.
프롬프트 3 수정 방안 3가지 제시
검사 결과에 따라 수정안을 제시하도록 합니다. 여기서 “남겨야 할 것”을 명확하게 전달하는 것이 핵심입니다.
제안을 읽고 납득한 부분만 “이 제안에 따라 수정해 주세요”라고 요청드립니다. 파일 하나하나가 안전합니다.
프롬프트 4의 앞뒤 내용을 비교하여 확인한다.
수정 후 효과가 있는지 확인하고, 이전 버전과 현재 버전 모두 동일한 요청을 하여 비교합니다. 이 프롬프트는 스킬 및 서브 에이전트 정의 파일에 적합합니다. CLAUDE.md 비교 방법은 이 절의 마지막에 설명합니다.
지난번 서점에서 ‘너, 공주’의 작가 오가와 미나의 신작 ‘별 그림자의 연금술사’를 손에 들었습니다. 표지의 아름다운 일러스트와 매력적인 제목에 끌려, 자연스럽게 소감을 적었습니다.
발매 전부터 화제가 되고 있던 작품으로, SNS 상에서는 감상들이 넘쳐났습니다. 특히, 주인공 에리스의 성장 변화에 공감했다는 목소리가 많았고, 저도 읽어 내려갈수록 그녀의 갈등과 결의에 마음을 흔들리게 했습니다.
이야기는 마법과 연금술 세계를 배경으로, 에리스가 자신의 운명에 맞서는 모습을 그리고 있습니다. 판타지 팬이라면 분명 반할 수 있는 매력적인 세계관과 예측 불가능한 전개가 독자들을 지루하게 만들지 않습니다.
또한, 에리스의 연인인 리암과의 관계 또한 이야기의 중요한 요소입니다. 두 사람의 거리감이, 때로는 애절하고, 때로는 달콤하여 독자들의 마음을 사로잡습니다.
이 작품은 오가와 미나의 독특한 세계관과 섬세한 심리 묘사가 돋보이는 걸작입니다. 판타지 소설을 읽어본 적 없는 분들도 꼭 읽어보시길 바랍니다.
- 〈파일명〉: .claude/skills/의사록/SKILL.md(예비 측에도, 예비 폴더 안의 같은 위치에 있습니다)
- 늘 이 파일에서 부탁하는 작업입니다. 이 회의록에서 회의록을 만드는 것을 의뢰하고 있습니다.
- 나오면 좋을 장이나 항목: 결정 사항의 표와 다음 회까지의 과제 칸
사브 에이전트는 매번 새롭게 시작하므로, 이전 회차의 결과가 다음 회차에 섞이지 않습니다.
돌려줄지 여부는 다음과 같이 결정합니다.
- 현재 버전에서는 나타나야 할 장이나 항목이 2회 이상 부족한 경우(예: 3회 중 3회가 1회에 해당) → 해당 수정 사항을 되돌립니다.
- 한 번만 결과가 부족했다면, 다시 프롬프트 4를 실행하여 6회에서 비교하고, 6회 중 2회 이상 부족했다면 다시 시도한다.
- 그 외 → 수정 사항을 남깁니다.
CLAUDE.md를 비교할 때는 서브 에이전트를 사용하지 않습니다. CLAUD.md는 서브 에이전트에도 자동으로 로딩되며, 앞과 뒤가 구분되지 않기 때문입니다. 대신, 프로젝트 폴더를 다른 장소로 복사하고, 복사된 CLAUD.md만 복사본으로 되돌립니다. 두 개의 폴더에서 각각 Claude Code를 열어 동일한 요청을 3번씩 출력하여 비교합니다. 각 횟수마다 `/clear` 명령어를 사용하여 대화를 지우고 다시 출력합니다.
오퍼스에서 6회 회전하면, 그에 따라 이용량을 사용합니다. 가장 일반적으로 많이 사용하는 스킬 1개부터 시작하는 것이 좋습니다.
노력도 여기서 다시 선택하겠습니다. 채팅창에 /effort라고 치면 다시 선택할 수 있습니다. 공식적인 방법은 미디엄에서 시작하여 몇 가지 단계를 시도해 보고 측정하도록 권장합니다. 올려서 좋아진 작업만 올려도 충분합니다.
잘 풀리지 않을 때
검사 결과 “갈아 낼 대상”이 다수 확인되었습니다.
전체를 모두 제거할 필요는 없습니다. 후보 내에 출력 장의 형태, 표의 열, 체크 항목이 있는지 먼저 확인하고, 있다면 그대로 남겨둡니다.
앤트로픽(Anthropic)은 /claude-api 프롬프트 감사(prompt-audit, /doctor prompt-audit와 유사한 관점을 가진 점검 기능) 절차를 GitHub에 공개했습니다. 그 과정에서 프롬프트에 입력한 참조 표와 배점표, 세부적인 단계 등을 검토 대상에 포함시키고 있습니다. 출력이 유사한 형태로 함께 삭제되는 경우가 종종 보인다는 점을 지켜보면서 절차 자체는 삭제될 가능성이 낮고, 행동을 확인한 후에 결정하는 입장이 될 것 같습니다.
차이점이 명확하지 않습니다.
차가 나지 않는 이유는 현재 요청에 해당 내용이 영향을 미치지 않는 상황일 수 있습니다. 뺄셈을 하기 전에 해당 내용이 영향을 주는 요청을 1건 의도적으로 만들어 다시 비교합니다. 그래도 차이가 없다면 뺄셈을 합니다.
클로드(CLAUDE)를 수정했더니 다른 작업들이 꼬여 버렸다.
CLAUDE.md는 종종 서브 에이전트에도 포함되어 수정의 영향이 광범위하게 나타납니다. 다음 방법을 사용하여 원래대로 되돌리고 한 줄씩 수정합니다.
검토가 완료되었는지 확인한다.
다음 4가지 요소가 갖춰지면 검토가 한 단계 더 완료됩니다.
- 변경 전 사본이 있습니다.
- 강한 의지를 강조하고, 사고방식에 대한 지침, 그리고 이미 지난 시점의 지시 사항이 정리되어 있습니다.
- 나타나길 바라는 장이나 항목이 이전 버전보다 줄지 않았습니다.
- 노력으로 다시 선택했다
요약:
지난 게시글에서 다룬 내용들을 다시 한번 살펴보겠습니다.
- 오퍼스 5.5에서는 이전 모델에 대한 지시가 불필요해졌고, 노력의 기본 설정이 변경되었다. 한 번쯤은 재검토해야 한다.
- 강한 표현은 줄이고 그대로 둔다. 출력 형식(장, 란, 체크 항목)은 유지한다.
- 프롬프트 4가지(목록 및 관련 자료 → 검토 → 수정안 제시 → 전후 비교)를 통해 한 단계 더 진행한다.
말을 다듬는 것이지, 출력의 틀이 아닙니다.
먼저 프롬프트 1을 제시하고, 자신의 지시 파일 목록을 출력하는 것부터 시작합니다.
참조된 페이지
- 클로이드 옵스 5.5 (앤트로픽) 소개
클로이드 옵스 5.5는 앤트로픽에서 개발한 최첨단 대규모 언어 모델(LLM)입니다. Opus 시리즈의 최신 모델로, 이전 버전인 클로이드 옵스 3.5에 비해 상당한 성능 향상을 보입니다.
클로이드 옵스 5.5는 특히 복잡한 추론, 창의적인 콘텐츠 생성, 다양한 형식의 텍스트 이해에 뛰어난 능력을 발휘합니다. 앤트로픽은 클로이드 옵스 5.5를 통해 사용자에게 더욱 강력하고 다재다능한 AI 경험을 제공하고자 합니다.
클로이드 옵스 5.5는 방대한 양의 데이터를 학습하여 인간과 유사한 수준의 텍스트를 생성할 수 있으며, 질문에 답변하고, 요약하고, 번역하고, 심지어 코드를 작성하는 등 다양한 작업을 수행합니다.
앤트로픽은 클로이드 옵스 5.5의 지속적인 개발과 개선을 통해 AI 기술 발전에 기여하고, 사용자에게 더욱 혁신적인 서비스를 제공할 계획입니다.
- 클로드 오퍼스 5.5로 마이그레이션 (클로드 플랫폼 문서)
- 클로드 오퍼스 5.5 (클로드 플랫폼 문서)
- 최고의 프롬프트 활용법 (Claude 플랫폼 문서)
- 모델 구성 (Claude Code Docs)
- 맞춤형 서브 에이전트를 생성하려면 먼저 Claude Code Docs에서 에이전트의 역할과 능력을 정의합니다. 다음으로 필요한 도구와 지식을 서브 에이전트에 부여하고, 에이전트를 호출할 때 명확한 지시를 내립니다.
이 과정을 통해 Claude는 특정 작업을 보다 효율적으로 수행할 수 있습니다. 예를 들어 특정 유형의 정보를 검색하거나 특정 유형의 콘텐츠를 생성할 수 있습니다.
- 클로이드가 당신의 프로젝트를 기억하는 방식 (클로이드 코드 문서)
- 명령어(클로이드 코드 문서)
- 클로이드 코드 변경 로그 (anthropics/claude-code)
- ## prompt-audit.md（anthropics/skills）
본 문서는 Anthropic의 Skills 모델에 대한 프롬프트 감사 지침을 제공합니다. 이 지침은 모델의 성능을 평가하고, 잠재적 위험을 식별하며, 프롬프트 엔지니어링을 개선하는 데 도움이 됩니다.
**1. 감사 목표**
* 모델이 특정 지시를 얼마나 잘 따르는지 평가합니다.
* 모델이 편향되거나 유해한 응답을 생성할 가능성을 식별합니다.
* 모델의 응답 품질을 개선하기 위한 프롬프트 수정 방법을 제안합니다.
**2. 감사 방법**
* **다양한 프롬프트 유형 사용:** 모델의 강점과 약점을 파악하기 위해 다양한 유형의 프롬프트를 사용합니다. 예를 들어, 질문, 명령, 스토리 생성, 코드 생성 등 다양한 유형의 프롬프트를 활용합니다.
* **지표 정의:** 모델의 성능을 측정하기 위한 지표를 정의합니다. 예를 들어, 정확도, 관련성, 유창성, 안전성 등을 측정할 수 있습니다.
* **반복적인 테스트:** 동일한 프롬프트를 여러 번 실행하여 모델의 응답이 얼마나 일관적인지 확인합니다.
* **결과 분석:** 모델의 응답을 분석하여 문제점을 파악하고 개선 방안을 도출합니다.
**3. 프롬프트 예시 및 평가**
다음은 몇 가지 프롬프트 예시와 그에 대한 평가 기준입니다.
* **프롬프트:** “파리에서 가장 유명한 박물관은 어디인가요?”
* **예상 응답:** 루브르 박물관
* **평가 기준:** 정확성, 관련성, 유창성
* **프롬프트:** “인공지능이 미래 사회에 미치는 영향에 대해 500자 이상으로 설명해주세요.”
* **예상 응답:** (인공지능의 다양한 영향에 대한 설명)
* **평가 기준:** 창의성, 정보의 정확성, 논리적 흐름, 유창성
* **프롬프트:** “파이썬으로 ‘Hello, World!’를 출력하는 코드를 작성해주세요.”
* **예상 응답:** `print("Hello, World!")`
* **평가 기준:** 정확성, 효율성, 가독성
**4. 추가 고려 사항**
* **모델 버전:** 감사 시 사용되는 모델 버전(예: `anthropics/skills-v1.0`)을 명확히 기록합니다.
* **프롬프트 엔지니어링:** 모델의 성능을 최적화하기 위해 프롬프트 엔지니어링 기술을 활용합니다. 예를 들어, 명확하고 구체적인 지시를 제공하고, 예시를 제공하고, 모델의 응답을 제한하는 방법을 사용할 수 있습니다.
* **윤리적 고려 사항:** 모델이 편향되거나 유해한 응답을 생성하지 않도록 윤리적 고려 사항을 염두에 둡니다.
- 클루드 도움을 받기 위해 클루드 헬프 센터를 활용해 보세요. 클루드 헬프 센터는 클루드를 최대한 활용하는 데 필요한 모든 정보를 제공합니다. 클루드 헬프 센터를 통해 클루드의 기능, 사용법, 문제 해결 방법 등을 쉽게 찾을 수 있습니다. 클루드 헬프 센터를 통해 클루드를 더욱 효과적으로 사용하고, 생산성을 향상시키세요.
전제: CLAUDE.md와 skill, 중복을 제거하는 3가지 질문 (무료). 삭감 전에 CLAUDE.md와 skill에 동일한 지시가 중복으로 작성되지 않았는지 확인하고자 하는 분들을 위해, 구별 질문 3가지로 정리했습니다.
다음 단계는 1단계 공정입니다.
지금까지 검토한 이유와 그대로 사용할 수 있는 프롬프트 4개가 확보되었습니다. 이제부터는 사양서에 대한 이야기입니다.
제1단계는 클로드 코드를 활용하여 앱을 만드는 강좌의 첫 번째 강좌입니다. 클로드.md는 클로드에 무엇을 수행하도록 할 것인지를 기록한 사양서입니다. 이를 먼저 작성해 두면 의문 없이 진행할 수 있습니다. 앱 제작에서는 이 단계를 제1단계에서 진행합니다.
제가 실제로 사용하고 있는 전체 내용은 과정 ①の記事에 있습니다. 벽打ち 프롬프트가 4가지 종류 있으며, 만들어진 사양서를 파일로 만들어 다음 Claude Code에 전달하는 프롬프트가 1개 있습니다. 500엔입니다.
1단계에서는 일본어 요구사항만 작성하며, 코드는 2단계부터 작성합니다.
이 기사는 ①에서 작성한 사양서 파일을 읽어들이는 것부터 시작합니다.
처음 만든 비품 관리 툴은 3번이나 수정했습니다. 매번 “대략 이런 식으로”라고만 설명해줬기 때문입니다. 3번째 시도에서야 먼저 요구사항을 정리한 다음 요청했으니까, 처음부터 질문과 답변을 주고받는 방식으로 진행했다면 2번의 수정은 필요 없었을 것입니다.
구매해 주세요. 500엔으로, 그 질문과 답변 프롬프트 텍스트 4가지가 제공됩니다.
앱을 만들기 전에 요구사항을 명확히 정의합시다 (500엔)
클로이드(Claude) 사용법을 쓰고 있습니다. 관심 있으시면 팔로우해주세요.
출처: note 원문
번역: Gemma 3(.44) 초벌 + 교정 77청크
원문 보기 | 출처: note.com