같은 저장소에서 작업할 때마다 테스트 명령을 다시 알려 주고, 문서 조사 때마다 확인 순서를 붙여 넣는다면 지침에 담을 내용이 늘어납니다. Claude Code의 프로젝트 메모리 안내는 여러 작업에 적용할 규칙과 특정 업무의 절차를 구분하고, 반복되는 여러 단계의 절차는 스킬로 옮길 대상으로 설명합니다.
반복되는 문제에 맞춰 고칠 곳을 정합니다
작업 종류가 바뀌어도 계속 적용할 기준은 프로젝트 지침에 둘 후보입니다. 빌드·테스트 명령, 코드 작성 규칙, 프로젝트 구조처럼 같은 저장소에서 공유할 내용이 여기에 들어갑니다. Codex의 프로젝트 지침 안내도 AGENTS.md를 작업 전에 읽을 지침 파일로 설명합니다.
특정 보고서나 검토 작업에서 입력, 확인 순서, 결과 형식이 반복된다면 그 절차는 스킬에 담을 수 있습니다. Agent Skills 명세의 기본 단위는 SKILL.md가 있는 디렉터리이며, 참고 문서·템플릿과 실행 스크립트도 함께 둘 수 있습니다. 스킬 설명에는 언제 쓰는지, 본문에는 어떤 순서로 무엇을 남기는지 적습니다.
필요한 자료를 조회하거나 동작을 수행할 수단이 없다면 어떤 도구를 연결할지 살핍니다. MCP 서버 명세는 조회·실행 함수인 도구(Tools), 문맥 자료인 리소스(Resources), 재사용할 프롬프트(Prompts)를 정의합니다. 실제로 쓸 수 있는 기능은 서버가 제공하고 사용하는 앱이 지원하는 범위에 달립니다.
다음은 2026년 10월 15일 확인한 공식 문서의 역할 설명을 작업 문제에 적용한 선택 기준입니다.
| 반복되는 문제 | 먼저 살필 곳 | 담거나 확인할 내용 | 수정 뒤 확인할 결과 |
|---|---|---|---|
| 같은 저장소에서 테스트 명령을 매번 다시 알려 줌 | 프로젝트 지침 | 테스트 명령과 적용 범위 | 새 작업에서도 필요한 지침을 읽는지 |
| 같은 보고서에서 출처나 누락 항목 처리가 빠짐 | 스킬 | 조회 순서, 빠진 자료의 처리, 출력 형식 | 결과물에 근거와 미확인 사항이 남는지 |
| 필요한 문서나 서비스에 접근할 도구가 없음 | 도구 구성, 필요하면 MCP | 제공 기능, 연결 상태, 접근 권한 | 필요한 자료를 읽거나 동작을 요청할 수 있는지 |
한 업무에서 여러 문제가 겹치면 해당 요소를 함께 손볼 수 있습니다. 이미 설치된 명령줄 도구나 기본 검색 기능으로 자료를 가져올 수 있다면, 새 MCP 서버를 추가하지 않고 그 도구의 사용 절차를 스킬에 정리하는 것으로 시작할 수 있습니다.
공식 문서 조회에도 지침·스킬·연결이 함께 쓰입니다
오픈AI(OpenAI)는 Docs MCP 안내에서 공식 문서 검색 서버에 프로젝트 지침과 OpenAI Docs Skill을 함께 쓰는 구성을 제시합니다. 공식 예시의 openaiDeveloperDocs 서버는 개발자 문서를 검색하고 본문을 읽는 기능을 제공합니다. 읽기 전용이며, 사용자를 대신해 OpenAI API를 호출하지 않습니다.
이 안내의 Codex 예시는 AGENTS.md에 오픈AI 제품·API 관련 작업에서 문서 서버를 사용하도록 적습니다. 어떤 작업에서 공식 문서 확인을 요구할지는 프로젝트 지침이 맡고, 서버는 실제 검색과 본문 조회를 제공합니다.
같은 안내가 소개하는 OpenAI Docs Skill은 Docs MCP를 먼저 사용하고, 대안으로 오픈AI 공식 도메인을 확인하는 절차를 담습니다. 스킬과 MCP의 관계를 설명한 오픈AI의 스킬 개념 문서는 도구 호출 순서, 불완전한 결과 처리, 최종 출력 내용을 스킬에 둘 수 있다고 설명합니다.
이 역할 구분을 적용하면, 문서는 조회되는데 답변에 출처가 계속 빠지는 문제는 조회 뒤의 확인·작성 절차를 점검할 대상입니다. 서버에 연결되지 않아 원문을 가져오지 못하는 문제는 연결 설정과 접근 조건부터 살필 대상입니다.
같은 파일 이름도 제품마다 읽는 조건이 다릅니다
Codex는 프로젝트 지침 문서에 따라 전역 지침과 프로젝트 루트에서 작업 디렉터리까지의 지침을 조합합니다. 같은 디렉터리에서는 AGENTS.override.md를 AGENTS.md보다 먼저 찾으며, 한 디렉터리에서 최대 한 파일을 포함합니다.
Claude Code의 프로젝트 메모리 문서는 AGENTS.md 직접 읽기에 v2.1.277 이상이 필요하다고 명시합니다. 내장 AGENTS 플러그인을 끈 세션이나 일부 업그레이드 직후 세션에는 이 기능이 제공되지 않습니다. v2.1.281 이전에는 Amazon Bedrock이나 텔레메트리를 끈 환경 등 일부 세션에서 CLAUDE.md만 읽는 제한도 있었습니다.
Claude Code의 기본 설정은 작업 디렉터리와 상위 경로에 프로젝트 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 있는지 확인합니다. 하나라도 있으면 그쪽 프로젝트 지침을 읽고, AGENTS.md를 기본 대체 파일로 읽지 않습니다. 사용자 전역 ~/.claude/CLAUDE.md, 조직 관리형 지침, .claude/rules/는 이 선택 검사에서 제외됩니다. 두 형식을 함께 읽는 설정은 /config의 Project instructions에서 바꿉니다.
스킬의 자동 선택을 끄는 설정도 제품별로 다릅니다. Codex의 스킬 안내는 agents/openai.yaml의 policy.allow_implicit_invocation: false를, Claude Code의 스킬 안내는 SKILL.md의 disable-model-invocation: true를 설명합니다. 각 설정은 해당 제품의 파일에 넣습니다.
실패한 작업 한 건으로 수정할 범위를 좁힙니다
스킬과 MCP를 고를 때 파일이 저장된 장소만 기준으로 삼기는 어렵습니다. MCP 전송 명세에는 클라이언트가 실행한 로컬 프로세스와 표준 입출력(stdio)으로 통신하는 방식도 있습니다. Agent Skills 명세에 따라 스킬에 실행 스크립트를 넣을 수도 있으므로, 필요한 절차와 연결 기능을 각각 확인해야 구분할 수 있습니다.
반드시 막아야 할 실행이 문제라면 실행 권한을 통제하는 설정도 따로 봅니다. Claude Code 메모리 안내는 자연어 지침을 컨텍스트로 취급하며, 모델의 판단과 관계없이 동작을 막는 용도로 PreToolUse 훅을 안내합니다.
반복해서 실패한 작업 한 건을 골라 기대한 기준, 빠진 단계, 접근하지 못한 자료를 기록하는 것부터 시작하는 편이 좋습니다. 수정한 뒤에는 같은 요청으로 어느 지침과 스킬이 읽혔는지, 필요한 도구를 쓸 수 있었는지, 결과물의 누락된 내용이 채워졌는지를 확인합니다. 공통 기준과 작업 절차는 각각 한곳에서 고치도록 두고, 필요한 연결만 더합니다.
자료 확인 기준: 2026년 10월 15일. 공식 문서 조사에 근거하며 제품 설치·연결 시험은 수행하지 않았습니다.