掘金2026년 10월 31일 12:49중국어 → 한국어

Skill·MCP·Workflow·Rules·Memory 차이를 실제 개발 작업으로 설명

작성자는 Claude Code와 Codex 등 여러 도구를 오가며 Skill, MCP, Workflow, Rules, Memory 개념 차이를 실제 개발 작업 사례로 풀어냈다.

중국어 원문을 AI로 번역했습니다. 고유명사와 수치는 원문 표기를 우선하며, 중요한 판단에는 아래 출처 원문을 함께 확인하세요.

나는 Claude Code, Codex, Pi-Bolt를 번갈아 쓰는데, 자주 이런 상황을 겪는다. 그저 AI한테 페이지 하나 써 달라고 부탁하고 싶을 뿐인데, 설정 파일에서 명사들이 한 줄씩 튀어나온다. 마치 볼일 보러 가기 전에 자격증부터 따야 하는 것 같다.

"Figma 디자인 시안에 따라 페이지 구현"을 예로 들면, MCP는 디자인 시안에 접속하는 일을 맡고, Skill은 이미지를 어떻게 처리할지 규정하며, Workflow는 확인과 실행의 순서를 정하고, Rules는 어떤 파일을 건드리면 안 되는지 제한하며, Memory는 다음에 또 필요한 약속을 남겨 둔다.

이것들은 함께 쓸 수 있고, 분업은 대략 다음과 같다.

각 제품의 명명은 서로 겹치기도 한다. 한 Skill이 Workflow를 포함할 수 있고, 어떤 클라이언트는 규칙 파일을 "Memory" 메뉴에 넣어 둘 수도 있다. 그것이 무엇을 하는지는 로딩 시점, 유지보수 방식, 실행 동작을 봐야 판단할 수 있다. 메뉴 이름만 보고 판단하면 친척을 잘못 알아보기 쉽다.

뒤에서 언급하는 Agent는 파일을 읽고 쓰고 도구를 호출할 수 있는 AI 어시스턴트를 말하며, 호스트는 그것을 실행하는 클라이언트를 가리킨다.

1. 먼저 디자인 시안 이미지 처리부터

나는 미니프로그램을 개발할 때 Figma에서 소재를 내보내고, PNG를 압축하고, 텐센트 클라우드 COS에 업로드하고, 주소를 복사해서 다시 코드에 넣는 일을 자주 한다. 페이지를 아직 쓰기 시작하지도 않았는데, 나는 이미 이미지의 택배 기사가 되어 버린 셈이다.

한 페이지에 이미지가 여러 장 있으면 이 과정을 여러 번 반복해야 한다. 그래서 나중에 이것을 image-auto-upload Skill로 만들었는데, 두 개의 스크립트가 들어 있다. 하나는 PNG를 압축하고, 하나는 COS에 업로드하며, 소재 처리를 페이지 개발에 연결했다.

전체 과정은 《나는 Claude Code Skill을 하나 만들어서, 더 이상 수동으로 이미지를 자르고 COS에 올리지 않는다》에 적어 두었다.

당시 나는 Figma MCP로 디자인 시안을 읽었다. 이미지를 어떻게 압축하고, 어디로 보내고, 어떻게 링크를 반환하는지는 Skill이 설명하고, 먼저 소재 목록을 확인한 뒤 업로드하는 것은 이 작업의 Workflow다. 키가 코드와 로그에 나타나서는 안 된다는 것은 장기 규칙에 남기는 것이 적합하다.

실제로 압축 서비스와 COS SDK를 호출하는 것은 스크립트다. AI는 현재 작업에 어떤 단계를 거쳐야 하는지 판단하고, 호스트 도구를 통해 그것들을 실행한다.

이미 있는 스크립트로 작업을 완료할 수 있고 Agent도 명령을 실행할 수 있다면, 우선 그렇게 써도 된다. 설정을 갖추기 위해 각 스크립트에 MCP를 한 겹씩 덧씌울 필요는 없다. 이미지도 아직 올리지 못했는데 서비스를 하나 더 유지보수하는 것은 계산이 맞지 않는다.

예전 글에서는 업로드 성공 후 원본 이미지를 정리하는 방식을 채택했다. 지금 새내기에게 비슷한 과정을 설계해 준다면, 나는 먼저 원본 파일을 보관하고, 원격 결과를 검증한 뒤 약속에 따라 정리할 것이다. 키는 제출하지 않는 환경 파일에 넣더라도 로그, 스크린샷, 도구 출력이 그것을 밖으로 끌고 나가지 않도록 대비해야 한다.

2. Rules: 거듭해서 바로잡은 일을 적어 두기

AI 프로그래밍을 막 시작했다면, 나는 먼저 규칙 몇 개를 쓸 것이다.

"덤으로 다른 문제까지 같이 고치지 말 것", "작업 영역에 원래 있던 수정을 네가 이번에 한 것으로 치지 말 것", "테스트를 돌리지 않았으면 안 돌렸다고 쓸 것" 같은 요구는 이미 여러 번 말했을지도 모른다. 나는 버튼 하나만 추가하고 싶을 뿐인데, 덤으로 저장소 절반을 리팩터링한 선물을 받고 싶지는 않다.

이런 요구는 장기 지시 파일에 넣는 것이 적합하다. Claude Code에서 흔한 것은 CLAUDE.md이고, Codex와 Pi에서 흔한 것은 AGENTS.md다. 클라이언트가 파일을 어떻게 발견하고 어느 범위에서 로딩할지를 결정한다.

프로젝트에는 먼저 이렇게 몇 개를 써 둘 수 있다.

프로젝트 협업 약속 - 수정 전에 작업 영역을 먼저 확인하고, 현재 작업과 무관한 변경은 보존한다. - 프로젝트의 기존 컴포넌트와 의존성을 따르고, 새 의존성을 추가하기 전에 이유를 설명한다. - 인터페이스 실패 시 반드시 오류 정보를 보존하고, 빈 데이터로 성공을 가장하지 않는다. - 수정 후 관련 검사를 실행하고, 통과·실패·미실행 항목을 기록한다. - 명확한 승인이 없으면 코드를 스테이징, 커밋, 푸시하지 않는다.

각 항목은 구체적인 행동 하나에 대응할 수 있다. 문제가 생겼을 때 어느 항목이 지켜지지 않았는지 확인하기도 편하다. 나는 이런 것들을 쓰는 편이 좋고, AI에게 먼저 "세계 최고의 엔지니어"라는 칭호를 줄지 말지는 나중에 해도 된다.

모든 규범이 매 작업마다 따라 출근하게 하지 말 것

개인 모든 프로젝트에 적용되는 선호는 사용자 수준에, 팀이 공유하는 빌드 명령과 디렉터리 약속은 프로젝트 수준에, 인터페이스 디렉터리만 관리하는 규범은 가능한 한 그 범위로 한정한다.

예를 들어 Claude Code는 경로 규칙을 .claude/rules/api.md에 둘 수 있다.

--- paths: - "src/api/**/*.ts" --- 인터페이스 호출을 수정할 때는 기존 요청 래퍼를 따른다. 페이지 컴포넌트에서 서버 주소를 중복해서 이어 붙이지 않는다.

이것은 Claude Code의 구체적인 문법이므로, 다른 도구로 옮기려면 지원 방식을 따로 확인해야 한다.

여러 파일로 나누더라도 그것들이 어떻게 로딩되는지도 확인해야 한다. 메인 파일이 모든 규범을 직접 불러온다면, 모델은 매번 여전히 잔뜩 읽을 수 있다. 무관한 컨텍스트를 줄이고 싶다면 클라이언트가 지원하는 경로 범위나 필요 시 읽기 메커니즘을 함께 써야 하며, 파일을 다른 곳으로 옮기기만 해서는 안 된다.

규칙도 오래 쓰면 정리해야 한다. 프로젝트가 npm에서 pnpm으로 바뀌면 옛 명령은 업데이트해야 하고, 임시 장애 대응 중에 추가한 제한은 끝난 뒤 다시 남길지 살펴봐야 한다.

정말 허용할 수 없는 동작에 대해서는 Markdown 속의 "금지"는 그저 하나의 지시일 뿐이다. 권한, 샌드박스, 명령 검사, CI가 해당 단계에서 막을 수 있지만, 구체적으로 어디까지 막을 수 있는지는 확인해야 한다. 파일에 "엄금"을 세 번 써 넣는다고 해서 자동으로 출입문이 하나 더 생기지는 않는다.

3. Skill: 이런 일은 다음에 이 문서대로

Skill을 어떻게 써야 할지 자신이 없을 때는, 나는 먼저 skill-designer로 구조를 정리한다. 그것은 적용 장면, 진입점 설명, 참고 자료의 분업을 정리하는 데 도움을 준다. cc, pi, codex 등 agent에서 이렇게 요구할 수 있다.

skill-designer 다운로드 클릭

/skill-designer "페이지 문제 점검"을 하나의 Skill로 정리해 줘. 먼저 적용 장면과 입력을 확인하고, 읽기 전용 분석과 코드 수정을 구분해 줘. 연결 실패 시의 처리 방식과 납품 전 점검 지점을 나열해 줘. 어떤 내용을 진입점에 넣고, 어떤 것을 참고 문서로 나누고, 어떤 것을 스크립트로 쓰는 게 적합한지 설명해 줘.

이것은 내가 직접 사용하는 Skill이라서, 먼저 클라이언트가 발견할 수 있는 위치에 설치해야 한다. 도구마다 호출 문법도 다르므로, 뒤에 대조표가 있다.

초안이 나온 뒤에도 여전히 실제 작업으로 시험해 봐야 한다. 잘못 트리거되지는 않는지, 단계를 빠뜨리지는 않는지, 실패 후에 솔직하게 멈출 수 있는지 살펴봐야 한다. 디렉터리가 깔끔해 보이는 것과 실제로 일이 제대로 되는 것은 따로따로 확인해야 한다.

어떤 작업을 Skill로 만들 만한가?

같은 요구 사항을 반복해서 붙여넣기 시작하거나, 한 번의 재작업이 재사용 가능한 방법을 남겼을 때, 나는 Skill로 만들 생각을 한다. 다음에 다시 할 때 적어도 먼저 채팅 기록에서 유물을 발굴하듯 찾아볼 필요는 없으니까.

이미지 업로드, 코드 리뷰, 특정 유형의 인터페이스 문제 점검 등은 모두 정리해둘 수 있다. 먼저 작업의 진입점과 완료 기준을 명확히 하고, 그다음에 어떤 파일이 필요한지 결정한다.

흔한 디렉터리 구조는 이렇다:

page-check/ ├── SKILL.md ├── references/ │ └── checklist.md └── scripts/ └── check-output.mjs

SKILL.md는 언제 쓰고 어떤 단계로 하는지를 설명한다. 자세한 점검 항목은 references에 넣을 수 있고, 안정적이고 반복적인 계산과 검증은 스크립트에 맡긴다. 스크립트가 없어도 Skill을 만들 수 있으니, 디렉터리를 전문적으로 보이게 하려고 빈 폴더를 한 줄 먼저 만들어 둘 필요는 없다.

첫 번째 Skill은 트리거 조건과 결과물만 명확히 써도 충분하다

이것은 글쓰기 방식을 보여주기 위한 간소화된 페이지 점검 예시이며, 아직 검증된 범용 트러블슈팅 도구는 아니다:

--- name: page-check description: 실행 중인 페이지의 표시 및 상호작용 문제를 점검한다. 사용자가 페이지 장애 재현을 요청할 때 적용한다. 코드만 읽는 경우에는 사용하지 않는다. --- 1. 대상 페이지, 실행 환경, 사용자가 본 이상 현상을 확인한다. 2. 프로젝트의 시작 및 검증 설명을 읽은 뒤 실제 페이지를 연다. 3. 재현 절차를 기록하고 관련 DOM, 콘솔, 네트워크 요청을 점검한다. 4. 코드를 대조해 원인을 찾는다. 수정 권한이 없을 때는 분석 결론만 제시한다. 5. 수정 권한을 얻은 뒤 수정하고, 원래 절차대로 다시 테스트한다. 6. 원인, 변경 범위, 검증 결과, 미검증 항목을 전달한다. 브라우저 연결에 실패하면 차단 사유를 설명하고, 코드 추론을 현장 재현으로 쓰지 않는다. 자세한 점검 항목은 references/checklist.md를 참고하며, 페이지 점검에 들어갈 때 읽는다.

이것은 무엇을 해야 하는지, 그리고 연결 실패 시, 수정 권한이 없을 때 어떻게 처리할지를 설명한다.

설명에는 적용되는 경우와 적용되지 않는 경우를 쓰는 것이 좋다. "개발 경험 최적화"는 너무 넓어서 모델이 언제 써야 할지 결정하기 어렵다. 범위가 커지면 명령어 하나 물어봤을 뿐인데 온갖 검진을 다 끌려가게 될 수 있다.

"점진적 공개"는 쓰는 데까지 읽는 것이다

내가 쓰는 Pi-Bolt에서는 모델이 먼저 Skill의 이름, 설명, 경로를 보고, 사용하기로 결정한 뒤 본문을 읽는다. 본문은 모델에게 어느 단계에 이르면 해당 상세 자료를 읽으라고 안내할 수 있다.

Codex, Claude Code도 필요에 따라 로딩하는 사고방식을 채택하고 있으며, 구체적인 필드, 발견 규칙, 컨텍스트 예산은 다르다.

내가 예전에 미니어처 애니메이션 Skill을 만들 때는 화풍, 참고 이미지 처리, 움직임 점검, 오디오, 내보내기를 분리했다. 장면을 설계할 때는 인코딩 설명 전체를 읽을 필요가 없고, 실제 영상 제작 단계에서 읽으면 된다.

미니어처 애니메이션 Skill 다운로드

Skill과 Prompt, 신제커우 미니어처 애니메이션에 관한 그 글에서 나는 이렇게 썼다: "파일을 나누는 것만으로는 부족하고, 진입점에 읽는 시점을 명확히 써야 한다."

"Skill이 결국 Prompt인가"에 관해서라면, 본문은 물론 여전히 모델에게 보여주는 지시다. 내가 저장하는 것은 이런 작업의 설명, 자료, 템플릿, 스크립트, 그리고 언제 그것들을 읽을지다. 파일 이름을 바꾼다고 모델이 머리를 하나 더 갖게 되는 것은 아니다.

넷째, MCP: 외부 연결이 필요할 때 그때 설정한다

MCP의 전체 이름은 Model Context Protocol이며, 먼저 클라이언트가 도구와 데이터 서비스에 연결하는 일련의 프로토콜로 이해하면 된다. 브라우저 서비스는 페이지 읽기, 요청 점검 능력을 제공하고, 문서 서비스는 검색과 읽기를 제공하며, 디자인 도구 서비스는 디자인 시안 정보를 제공한다.

연결에 성공한 뒤에도 점검 방법, 대상 환경, 로그인 상태, 권한은 여전히 확인해야 한다. 브라우저 도구가 페이지를 열 수 있다 해도, 다음에 문제를 재현할지, 요청을 조회할지, 코드를 대조할지에는 여전히 일정한 방법이 필요하다.

언제 설치할 만한가

AI가 실행 중인 페이지를 직접 점검하고, 디자인 시안을 읽고, 문서 서비스를 조회하기를 원할 때는 성숙한 MCP 연동이 있는지 살펴볼 수 있다.

단지 로컬 파일을 읽고, 테스트를 실행하고, 이미지 몇 장을 처리하는 것뿐이고 클라이언트가 이미 파일 읽기와 명령 실행을 할 수 있다면, 기존 능력을 먼저 쓰면 된다. CLI, SDK, HTTP API 모두 요구를 충족할 수 있다.

내가 Tauri로 개발한 이 데스크톱 앱에는 쉽게 빠질 수 있는 함정이 하나 있다: MCP 브리지를 통해 실제 인터페이스를 점검할 때, 개발 버전은 반드시 dev-mcp 기능을 붙여 시작해야 한다. 일반 개발 명령으로도 앱은 열리지만, 브리지 기능은 컴파일되어 들어가지 않는다. 창은 멀쩡히 보이는데 연결이 안 되니, 인생을 의심하게 만들기에 딱 좋다.

이런 시작 요구 사항은 프로젝트 Skill에 적어두어, 이후 검증 시 먼저 설명을 읽게 하는 것이 좋다.

먼저 읽기 전용 서비스 하나를 연결해 실제로 한 번 조회한다

예를 들어 Codex는 ~/.codex/config.toml에서 공식 문서 MCP를 설정할 수 있다:

[mcp_servers.openaiDeveloperDocs] url = "https://developers.openai.com/mcp"

설정한 뒤 연결 상태를 확인하고, 다시 문서 하나를 조회하게 해서 반환 내용과 출처를 대조한다. 이 공식 읽기 전용 문서 서비스로는 그 때문에 당신의 데이터베이스나 클라우드 계정 권한을 얻지 못한다.

Claude Code, Pi의 형식과 위치는 다르므로 각자의 문서에 따라 설정해야 하며, TOML을 그대로 JSON에 붙여넣으면 안 된다.

일부 MCP는 원격 URL로 연결하고, 일부는 로컬에서 서비스 프로그램을 시작해 표준 입출력으로 통신해야 하며, 흔히 stdio라고 부른다. 후자는 Node, Python 등의 환경에 의존할 수 있고, 서버 설치와 파일 접근 권한 부여도 처리해야 한다.

목록에 이름이 나타난 뒤에는, 클라이언트가 설정을 읽었는지, 서비스가 연결됐는지, 필요한 도구를 호출할 수 있는지, 호출 결과가 올바른 환경에서 온 것인지 계속 점검해야 한다. 공개 페이지를 읽을 수 있다고 해서 로그인 후의 백엔드에 들어갈 수 있는 것은 아니고, 테스트 DB를 조회할 수 있다고 해서 프로덕션 DB에 쓰기 권한을 줘야 하는 것도 아니다.

브라우저는 특히 어떤 창과 세션에 연결되는지 잘 봐야 한다. 나는 환경을 확인하기 쉽도록 보이는 브라우저를 재사용하는 습관이 있다. 별도로 브라우저를 띄우는지, 어떤 연결 방식을 지원하는지는 구체적인 서비스에 달려 있다.

Chrome DevTools MCP: 웹페이지를 점검할 때, 나를 로그아웃시키지 마라

예전에 겪은 일인데, AI 세션을 새로 열면 Chrome이 연결 승인을 띄우고, AI에게 웹페이지를 열라고 하면 내가 보고 있던 탭을 또 전환해버렸다. 독립 브라우저로 바꾸면 로그인 상태는 분리됐다. 원래는 페이지 하나 점검을 도와달라고 한 것뿐인데, 결국 내가 먼저 그것에게 자리를 마련해줘야 했다.

당시의 전체 설정과 스크립트는: 《chrome-devtools-mcp가 자꾸 승인을 띄우고 탭을 뺏어가나요? 저는 이렇게 하나하나 설정했습니다》.

그때는 macOS, Codex CLI, 공식 패키지 1.12.0의 실천이었고, 각각 다음 문제들을 처리했다:

| 겪은 문제 | 당시의 처리 방법 | | --- | --- | | 독립 브라우저에 평소의 로그인 상태가 없음 | --autoConnect로 평소 쓰는 Chrome에 연결하고, 그것이 요구하는 원격 디버깅을 켬 | | 새 세션마다 연결을 다시 맺고 권한 승인 창이 뜸 | 직접 작성한 어댑터 스크립트로 공식 CLI의 상주 연결을 재사용 | | 새 웹페이지가 현재 탭을 가로챔 | 어댑터 스크립트가 강제로 백그라운드에서 페이지를 생성, 도구 컨텍스트를 전환할 때 탭을 활성화하지 않음 | | 프로젝트 설정에 개인 경로를 하드코딩 | Node와 런처의 개인 경로는 사용자 레벨 설정에 두고, 프로젝트 내 오래된 진입점은 정리 |

--autoConnect는 연결 대상을 선택하는 역할을 하고, 직접 작성한 quiet 런처는 호출을 전달하고 연결을 재사용하며 백그라운드 작업을 제약한다. 여기서 quiet는 추가로 맞춘 코드이며, 이 몇 가지 일을 하나의 공식 "quiet 스위치"가 처리해 주는 것은 아니다.

백그라운드에서 페이지를 생성할 때는 background: true를 쓰고, 작업 페이지를 선택하되 포그라운드를 빼앗지 않을 때는 bringToFront: false를 쓴다. 규칙으로 알려 주는 것 외에도, 당시 나는 어댑터 스크립트에 이 두 파라미터를 고정해 누락을 줄였다.

첫 연결은 여전히 사용자의 허용이 필요하다. Chrome이나 연결, 혹은 상주 프로세스가 재시작된 뒤에도 다시 권한 승인을 요구할 수 있다. 클라이언트가 도구 호출을 승인하는 것과 Chrome이 원격 디버깅을 허용하는 것은 두 층의 권한이며, 전자가 후자를 대신할 수 없다.

설정을 마친 뒤에는 별도의 AI 세션을 열어 테스트해야 한다. 원래 프로세스를 재사용하는지, 백그라운드로 페이지를 열 수 있는지, 원래 탭이 여전히 선택되어 있는지 말이다. 현재 세션에서 한 번 성공한 것이지, 세션 간 재사용까지 검증된 것은 아니다. 평소에도 작업 하나를 끝낼 때마다 습관적으로 공용 프로세스를 중지하지 말아야 한다.

이 설정에서 MCP는 브라우저 조작을 제공하고, 짝을 이루는 Skill은 사용법을 소개하며, Rules는 사용자의 기존 탭을 건드리지 않도록 제약하고, 어댑터 코드는 연결 재사용과 고정 파라미터를 처리한다. 런처는 특정 패키지 버전의 내부 모듈에 의존하므로, 업그레이드할 때 함께 점검해야 하고, 모든 시스템에 그대로 적용할 수도 없다.

서비스를 많이 설치하면 컨텍스트 비용도 고려해야 한다. 도구 정의, 호출 결과, 로그가 모두 공간을 차지할 수 있으며, 일부 클라이언트는 도구 발견이나 지연 로딩을 지원한다. 실제 비용은 MCP 개수만으로 계산할 수 없다. 우선 현재 작업에 쓰일 서비스만 남겨 두면, 연결에 문제가 생겼을 때 찾기도 쉽다.

5. Workflow: 순서와 확인 조건을 명확히 적기

어떤 제품은 반복 호출 가능한 Markdown 단계를 Workflow라 부르고, 어떤 제품은 상태를 저장하고 분기를 실행할 수 있는 워크플로 엔진을 제공한다. Skill 안에서 일련의 단계를 구성하는 것도 워크플로를 설계하는 것이다.

따라서 Skill은 워크플로를 담을 수 있다. 전자는 능력 패키지이고, 후자는 실행 과정을 기술한다. 구체적인 제품을 만나면, 그것이 어떤 기능을 Workflow라 부르는지도 따져 봐야 한다.

그림 속 거리 풍경은 예시이며, 실제 작품은 앞서 인용한 신제커우 애니메이션 답변에서 볼 수 있다. 내가 제작할 때 채택한 순서는 다음과 같다.

참고 이미지를 읽고 스타일 요구 사항을 확인 같은 애니메이션의 실제 샘플 프레임 네 장을 생성 내가 현재 버전을 확인할 때까지 대기 검사를 실행한 뒤 전체 영상을 렌더링 화면이나 스토리에 변경이 있으면 다시 확인

"먼저 보여 줘"라고 말하는 것은 너무 두루뭉술하다. 개념도인지 실제 프레임인지? 차량 형태를 인정한 것이 영상 전체를 승인한 것으로 치는지? 카메라를 바꾼 뒤에도 이전 승인이 유효한지? 칭찬 한마디가 영상 전체 제작 승인까지 덤으로 준다면, 그 혜택은 너무 큰 것 아닌가.

그래서 나는 나중에 승인 기록과 버전 대조를 보강해, 영상 산출 전에 프로그램이 승인이 현재 버전과 대응하는지 검사하도록 했다. Markdown은 따라야 할 순서를 설명하고, 코드 검사는 지정된 실행 진입점에서 조건에 맞지 않는 요청을 거부한다.

개발 작업도 이렇게 구성할 수 있다.

문제를 재현하고 증거를 기록 원인과 수정 범위를 확인 수정하고 관련 테스트를 추가 원래 단계에 따라 재검증 diff를 검사하고 검증 결과를 전달

확인 단계는 범위를 넓히거나, 비용을 발생시키거나, 데이터를 덮어쓰거나, 외부 시스템에 영향을 주는 단계에 둔다. 문구 한 줄 고칠 때마다 다섯 번씩 멈춰 승인받는다면 나도 견디기 힘들다. 연속해서 완료할 수 있는 부분은 연속해서 하게 둔다.

무인 운용, 고정된 분기, 신뢰할 수 있는 재시도가 필요할 때는 확정적 실행에 적합한 부분을 스크립트, CI 또는 워크플로 엔진에 맡기고, AI가 판단이 필요한 단계를 처리하게 할 수 있다. 자연어 목록만으로는 이러한 요구를 혼자 감당하기 어려울 수 있다.

6. Memory: 다음엔 처음부터 설명하게 하지 말 것

며칠 뒤 세션을 바꿔도 나는 AI가 이전에 확인한 약속을 찾아내길 바란다. 어떤 프로젝트는 당분간 의존성을 업그레이드할 수 없다든가, 어떤 환경은 특정한 방식으로만 기동할 수 있다든가, 혹은 먼저 분석을 하고 승인을 받은 뒤에야 코드를 수정할 수 있다든가 하는 것들이다.

이런 정보는 Memory로 저장할 수 있다. 안정된 선호, 확인된 결정, 여전히 유효한 환경 제약은 장기로 남겨 두기에 적합하다. 오늘 어떤 파일을 읽었는지, 어떤 테스트가 아직 실행되지 않았는지는 당일 기록이나 작업 진행 상황에 두는 편이 더 적합하다. 무엇이든 영구히 즐겨찾기 해 두면, 결국 메모 속에서 메모를 뒤져야 한다.

저장한 뒤에는, 다시 찾아낼 수 있는지도 시험해 봐야 한다

파일 이름이 MEMORY.md라고 해서 모델이 매번 전체를 읽는다는 뜻은 아니며, 내용이 모두 정확하다는 것을 증명하지도 못한다. 클라이언트가 어느 부분을 로딩하는지, 필요에 따른 검색이 있는지, 새로 추가한 기록이 얼마 만에 반영되는지, 오래된 정보는 어떻게 수정하거나 삭제하는지를 봐야 한다.

나는 Pi-Bolt에서 pi-memory 확장을 사용해, 장기 기록과 매일의 로그, 할 일을 분리해 저장하고, 읽기·쓰기·검색·망각 등의 도구를 제공한다. 검색은 선택적인 qmd 검색 도구에도 의존하며, 뜻으로 유사한 내용을 찾는 의미 검색에는 그에 맞는 인덱스와 모델이 필요하다. 이는 나의 확장 설정이며, Pi 자체를 설치한다고 해서 이 모든 기억 기능이 기본으로 딸려 오는 것은 아니다.

Claude Code에는 자체 auto memory가 있으며, 사람이 관리하는 CLAUDE.md와는 쓰기 방식과 용도가 다르다. Codex로 옮겨도 해당 버전과 설정이 무엇을 지원하는지 확인해야 한다. 양쪽 모두 Markdown을 읽을 수 있지만, 기억을 자동으로 동기화하기까지는 아직 해야 할 일이 적지 않다.

기억 기능이 이미 설정된 클라이언트에서는 이렇게 요구할 수 있다.

기억해 줘: 이 프로젝트에서는 명확한 승인 없이 코드를 스테이징하거나 커밋하지 마. 프로젝트 장기 약속으로 저장하고, 어디에 기록했는지 알려 줘. 테스트 계정, 키, 이번 라운드의 임시 로그를 장기 기억에 저장하지 마.

그런 다음 새 세션으로 바꿔, 약속이 무엇인지, 어디서 읽었는지 물어보고, 저장된 파일도 확인한다. "기억했다"는 한마디만 듣고 안심할 수는 없다. 내 기억력도 그렇게 장담할 만큼 좋지 않으니까.

범위와 이유를 남기고, 정리도 잊지 말 것

의존성 제약 한 건은 이렇게 기록할 수 있다.

범위: 현재 프로젝트의 결제 의존성. 결론: 당분간 기존 버전을 유지. 이유: 새 버전의 호환성이 아직 검증되지 않음. 재평가: 호환성 검증을 마친 뒤 업그레이드 여부를 다시 확인.

이는 예시이며, 실제 이유와 승인자는 진짜 논의에서 나와야 하고, 모델이 듣기 좋은 이유를 지어내게 해서는 안 된다. 결정이나 환경이 바뀌면 오래된 기록을 갱신하거나 삭제해야 하며, 그렇지 않으면 같은 오류가 기억을 타고 세션을 넘어 되살아난다.

규칙과 기억도 교집합이 있다. "승인 없이 푸시하지 않는다"는 개인 선호로 저장할 수도 있고, 장기적으로 준수해야 할 규칙으로 적을 수도 있다. 기억은 저장과 회수에, 규칙은 무엇을 준수하길 바라는지에 강조점이 있다.

운영 환경을 조작할 때는 여전히 다시 확인해야 한다. Memory는 지난번 상황을 알려 줄 수 있지만, 오늘의 환경은 이미 바뀌었을 수 있다.

7. 명령, 스크립트, Hooks는 또 각각 무엇을 관리하나?

같은 슬래시 진입점이라도 다른 도구로 옮기면 그 뒤의 메커니즘도 달라질 수 있다.

Pi의 Prompt Template은 자주 쓰는 프롬프트를 /review 로 만들 수 있다. 단지 검토 프롬프트 붙여넣기를 줄이고 싶을 뿐이라면 템플릿이면 충분하다. 참고 자료와 완전한 처리 방법이 필요할 때 비로소 Skill을 고려하라.

Claude Code는 이미 사용자 정의 Commands를 Skills 사용 체계에 통합했고, 기존 디렉터리도 여전히 호환된다. 모두 /이름 형태라고 해서 같은 메커니즘으로 바로 단정하지 마라.

스크립트는 고정된 로직을 실행한다. 파일 요약, 데이터 변환, 형식 검증처럼 결과가 명확한 작업은 Agent가 기존 스크립트를 호출하게 하는 편이 좋다. 매번 다시 추론하지 않아도 되니까.

Hooks는 특정 이벤트가 발생할 때 설정된 명령이나 점검을 실행하며, 지정한 단계에서 알림이나 차단에 적합하다. 어떤 Hook이 어떤 진입점을 커버할 수 있는지는 호스트 구현과 함께 검증해야 한다. Skill 안에 '도구 호출 전 점검'을 적는다고 해서 Hook이 자동으로 생성되는 것은 아니며, Hook을 설치했다고 해서 그것으로 모든 작업이 안전하게 격리된다고 볼 수도 없다.

플러그인은 Skill, 연결 및 기타 리소스를 패키징해 배포를 편하게 해준다. Pi 확장은 도구를 등록하거나 이벤트에 응답해 호스트 기능을 추가할 수도 있다. 당장의 작업에 이런 기능이 필요할 때 쓰면 되고, 미리 에디터를 도구 전시관처럼 꾸밀 필요는 없다.

八、Pi, Codex, Claude Code로 바꾸면 어떻게 적용할까?

흔한 로컬 진입점은 다음과 같다. ~는 사용자 홈 디렉터리이고, 프로젝트 디렉터리의 설정은 해당 프로젝트에 적용된다. 로딩 동작은 여전히 버전과 설정의 영향을 받는다.

도구 흔한 지시 파일 흔한 Skill 위치 명시적 호출 예시 Claude Code 사용자 레벨 ~/.claude/CLAUDE.md , 프로젝트 레벨 CLAUDE.md 사용자 레벨 ~/.claude/skills/ , 프로젝트 레벨 .claude/skills/ /page-check Codex 사용자 레벨 ~/.codex/AGENTS.md , 프로젝트 레벨 AGENTS.md 사용자 레벨 ~/.agents/skills/ , 프로젝트 레벨 .agents/skills/ $page-check , /skills 에서 선택도 가능 Pi, 나는 Pi-Bolt 사용 사용자 레벨 ~/.pi/agent/AGENTS.md , 프로젝트 레벨 AGENTS.md ~/.agents/skills/ , 프로젝트 .agents/skills/ 등 위치 지원 /skill:page-check

내 기기에서 구동하는 것은 pi-bolt 이고, Skill을 수정한 뒤에는 /reload 로 새로 고친다. 업스트림 Pi, Pi-Bolt, 버전별 차이 및 설치된 확장에 따라 차이가 있으며, 내 기기에서 쓸 수 있는 기능이 반드시 맨 Pi의 기본 설정 전부인 것은 아니다.

Claude Code도 현재 조건부로 AGENTS.md 읽기를 지원하며, 버전, 프로젝트에 이미 CLAUDE.md가 있는지, 관련 설정에 영향을 받는다. 여러 도구가 규범을 공유할 때는 실제 로딩 출처를 확인해야 하고, 호환이 필요하면 CLAUDE.md에서 @AGENTS.md 로 공유 내용을 불러올 수 있다.

내용은 되도록 공유하고, 연동 차이는 따로 처리

나는 몇몇 도구가 같은 Skill을 읽도록 하려고, 실체를 공유 디렉터리에 두고 전용 진입점이 필요한 도구를 위해 링크를 만든다. 세 벌로 복사해 두었다가 각자 다른 성격으로 자라는 것을 피하려는 것이다. 링크를 만들기 전에 기존 파일을 먼저 확인하고, 그냥 덮어쓰지 마라.

내용은 여전히 검토가 필요하다. Claude Code 특유의 필드, 하드코딩된 도구명은 Codex, Pi로 옮기면 적용되지 않을 수 있다. 작업 설명, 참고 자료, 일반 스크립트는 비교적 공유하기 쉽지만, 호스트 특유의 동작은 적응이 필요하다.

내가 이전에 쓴 《Claude Code 기초 공유》에서 Rules, Skill, MCP와 공유 디렉터리 사용 경험을 정리했는데, 관련 설정은 현재 버전 문서와 함께 확인해야 한다.

가끔 점검하라, 도대체 어느 것을 읽는지

내 Sessions Viewer는 Skill과 MCP 설정을 모아 보여주며, 평소에 이것으로 실체 디렉터리와 참조 관계를 점검한다. 같은 Skill의 여러 진입점과, 내용이 이미 갈라진 여러 사본은 각각 따로 처리해야 한다.

프로젝트 소스 · 버전 다운로드

같은 이름의 MCP라도 다른 파라미터가 설정되어 있을 수 있다. 그림 속 token은 캐시 추정 정의 오버헤드이며, 설정 상태가 현재 세션이 이미 연결되었음을 증명하지는 못하므로 여전히 실제 호출로 확인해야 한다. 관리 인터페이스를 쓰지 않고 파일을 직접 확인해도 된다.

九、설치 후 어떻게 검수할까?

같은 이미지 묶음으로 대조해 보라. 먼저 요구사항을 직접 주고, 그다음 Skill을 붙여서, 빠진 단계가 줄었는지, 결과를 더 쉽게 확인할 수 있는지 보라. 또한 키가 없을 때, 파일이 이미 존재할 때, 업로드가 실패할 때, 멈춰야 할 지점에서 멈추는지도 시험해 볼 수 있다.

정상 흐름이 돌아간 뒤에는 오작동, 도구 연결 끊김, 사용자가 임시로 요구사항을 바꾸는 경우를 계속 시험해 보라. 이런 상황이 설계상의 누락을 더 잘 드러낸다.

내려받은 Skill은 인용 파일과 스크립트까지 함께 봐야 하고, MCP 서비스도 출처와 권한을 확인해야 한다. '안전'이라고 적힌 설명서가 실제 실행되는 코드를 보증해 주지는 못한다. 먼저 테스트 디렉터리, 테스트 계정 또는 적절한 격리 환경에서 시험하고, 특히 삭제, 덮어쓰기, 업로드, 자격 증명 읽기 동작을 유의하라.

나는 마무리 보고 Skill을 하나 만들었는데, ask-report-html 이라고 한다. 작업이 길어지면 나는 항상 기록을 다시 뒤져 무엇을 바꿨고, 무엇을 테스트했고, 무엇이 아직 검증되지 않았는지 찾아야 해서, 버그를 찾는 것보다 사건을 수사하는 것처럼 뒤지게 되기 때문이다.

구체적인 설계와 설치 방식은 이 글 《ask-report-html에 관한 실전 답변》에 있다.

Skill은 내용과 생성 방법을 맡고, 규칙은 언제 호출할지를 설명하며, Workflow는 작업 전달 단계에 이르러서 정리하도록 요구한다. 세션을 바꿔 이어갈 때도 저장된 작업 기록이 진행 복구에 도움을 준다.

브라우저 검수를 하지 않았다면 '실행 안 함'이라고 써라. HTML 파일이 성공적으로 생성되었다고 해서 업무가 통과했음을 증명하지는 못하며, 보고서가 아무리 예뻐도 실행하지 않은 검사에 서명해 줄 수는 없다. 업로드 성공 후에야 파일을 정리하는 것과 마찬가지로, 완료 기준은 확인 가능해야 한다.

나는 앞으로도 반복 설명과 재작업이 줄어드는지, 실패할 때 충분한 정보가 남는지, 결과를 더 쉽게 검수할 수 있는지를 계속 지켜볼 것이다. 도구를 얼마나 많이 설치했는지는 이런 판단을 대체하지 못한다.

十、오늘 당장 해보고 싶다면, 어디서부터 시작할까?

손에 있는 작은 작업 하나를 골라, 먼저 기존 Agent로 해보라. 어디서 자꾸 반복 설명을 하게 되는지, 어느 단계에서 늘 사람이 개입해야 하는지를 확인한 다음, 그에 맞는 설정을 보충하라.

같은 요구사항을 늘 바로잡아야 한다면 규칙을 쓰고, 한 부류의 작업에서 단계를 반복 설명한다면 Skill을 정리하라. 기존 능력으로 외부 정보를 얻을 수 없을 때는 MCP를 연결하라. 긴 작업에서 확인 조건과 실패 분기가 나타나면 Workflow를 명확히 써라. 한동안 지났다가 돌아와서도 다시 설명해야 하는 확정된 정보는 비로소 기억에 저장하는 것을 고려하라.

구체적으로는 이렇게 할 수 있다.

- 짧은 프로젝트 지시를 하나 작성하고, 정말 자주 쓰는 약속만 넣는다.

- 이미 해본 적이 있고 다음에도 할 작업을 Skill로 정리하고, 적용 범위와 산출물을 명확히 쓴다.

- 외부 연동이 필요하다면 서비스 하나만 연결하고, 실제 반환 결과를 확인한다.

- 돈을 쓰거나, 파일을 덮어쓰거나, 외부 시스템에 영향을 주는 단계에는 확인 절차를 붙이고, 실패했을 때 멈추는지도 테스트한다.

- 다음에 새 세션으로 바꿔서 핵심 약속을 찾을 수 있는지 확인하고, 오래된 정보가 발견되면 업데이트한다.

먼저 앞의 두 단계만 해도 충분히 좋다. 작업이 필요해질 때 추가하면, 원래는 AI에게 코드 작성을 도와달라고 하려다가 결국 자신에게 설정 운영이라는 새 일거리를 만들어 주는 일을 피할 수 있다.

정리

하나의 개발 작업에 다시 넣어 보면, Rules는 장기적인 약속을 남기고, Skill은 이런 종류의 작업을 하는 방법을 저장하며, MCP는 도구와 데이터를 연결하고, Workflow는 순서와 확인 조건을 지정하며, Memory는 다음 세션에서 이미 확인된 정보를 다시 찾도록 돕는다. 이것들은 함께 쓸 수도 있고, 그중 한두 가지만 쓸 수도 있다.

잘 썼는지 여부는 결국 작업에서 단계를 빠뜨리지 않았는지, 결과를 검수할 수 있는지, 오류가 났을 때 사실대로 멈출 수 있는지에 달려 있다. 먼저 실제의 작은 작업 하나로 시험해 보는 것이 설정 목록을 놓고 하나씩 체크하는 것보다 효과를 더 쉽게 확인할 수 있다.

두 개의 Skill 첨부 파일 다운로드

- skill-designer 다운로드 : Skill의 적용 시나리오, 내용 구조, 체크포인트를 정리해 준다.

- 미니어처 애니메이션 Skill 다운로드 : 본문의 신지에커우(新街口) 사례에서 사용한 스킬로, 먼저 샘플 프레임을 보고 확인한 뒤 영상을 만든다.

문서 참고

- Claude Code：Skills 、 지시와 기억

- Codex：Skills 、 AGENTS.md 、 MCP

- Pi-Bolt 프로젝트 、 Agent Skills 규범 、 MCP 문서

jerrywus

프런트엔드 @쑤닝이거우

글

138k

조회

222

팬

출처 원문