AI 에이전트 기본 지시문 — 안 적으면 안전 지시가 빠집니다

코드로 에이전트를 만들 때 기본 지시문을 굳이 안 적어도 알아서 잘 돌겠지 싶습니다. 그런데 공식 문서를 보니 그때 붙는 건 도구 호출만 다루는 최소한이고, 보안·안전 지시와 작업 환경 정보는 통째로 빠집니다. 더 헷갈리는 건 터미널에서 한 번에 돌릴 때와 기본값이 다르다는 거예요. 옮겨왔는데 동작이 달라졌다면 십중팔구 이것 때문입니다. 정리했습니다.

📌 30초 요약

• ★★안 적으면 최소한만 붙습니다 — 안전 지시가 빠집니다.
• ★터미널에서 돌릴 때와 기본값이 다릅니다.
• 직접 쓰면 도구 안내·환경 정보까지 사라집니다.
• ★덧붙이기가 가장 안전합니다 — 빠지는 게 없습니다.
• ⚠️ 폴더가 다르면 캐시가 안 맞습니다.
• 프로젝트 지시문 파일은 지시문을 안 건드립니다.

안 적으면 최소한만 붙습니다

출발점이 세 가지입니다. 아무것도 안 적으면 최소 지시문, 터미널이 쓰는 것을 그대로 가져오는 기본 묶음, 그리고 내가 통째로 쓰는 것. 문제는 첫 번째예요.

최소 지시문은 도구를 부르는 방법만 담습니다. 나머지는 다 빠져요 — 보안·안전 지시도, 지금 어느 폴더에서 무슨 환경으로 돌고 있는지도 안 알려줍니다. "기본값이니 무난하겠지"가 아니라 의도적으로 얇게 만든 출발점인 거죠.

⚠️ 터미널과 기본값이 다릅니다

여기가 진짜 함정입니다. 터미널에서 한 번에 돌리는 방식은 완전한 지시문을 기본으로 씁니다. 그런데 코드로 옮기면 아무것도 안 적었을 때 최소한만 붙어요. 즉 같은 일을 시켰는데 동작이 달라집니다. 옮겨온 뒤 "왜 이렇게 굴지" 싶다면 기본 묶음을 명시적으로 지정해 보세요. 문서도 옮겨올 때는 그렇게 맞추라고 안내합니다.

직접 쓰면 안전 지시까지 사라집니다

"우리 제품 성격에 맞게 지시문을 새로 쓰자"는 판단은 종종 맞습니다. 다만 통째로 대체하면 보내지는 건 내가 쓴 것뿐이에요. 문서 표현이 분명합니다 — "에이전트에게 여전히 필요한 도구 안내와 안전 지시를 다시 채워 넣는 책임은 당신에게 있다"는 겁니다.

방식	안전 지시	환경 정보
기본 묶음 그대로	유지	자동
기본 묶음 + 덧붙이기	유지 — 빠지는 게 없음	자동
프로젝트 지시문 파일	유지 — 지시문을 안 건드림	자동
통째로 새로 쓰기	직접 넣어야	직접 넣어야
아무것도 안 적기	빠짐	빠짐

표를 보면 답이 나옵니다 — 기본 묶음에 내 규칙을 덧붙이는 방식이 가장 안전합니다. 아무것도 안 빠지고 내 지시만 뒤에 얹히거든요. 안전 지시를 덜어낸 모델을 일부러 고르는 경우도 있지만, 그건 알고 감수하는 선택이죠. 모르고 빠뜨리는 것과는 다릅니다.

폴더가 다르면 캐시가 안 맞습니다

같은 설정으로 여러 대에서 돌리는데 재사용 할인이 안 걸린다면 원인이 여기일 수 있습니다. 기본 묶음은 작업 폴더, 저장소인지 여부, 운영체제와 판, 쓰는 셸, 메모리 경로 같은 정보를 지시문 안에 박아 넣습니다.

그러니 폴더 하나만 달라도 지시문이 달라지고, 재사용이 통째로 어긋납니다. 이걸 끄는 설정이 있는데 환경 정보가 지시문 대신 첫 사용자 메시지로 내려가요. 맞교환이 있습니다 — 사용자 메시지에 실린 지시는 무게가 조금 덜해서, 지금 어느 폴더인지를 덜 강하게 참고할 수 있습니다. 여러 대가 캐시를 나눠 쓰는 게 더 중요할 때만 켜세요.

프로젝트 지시문은 다른 길로 들어옵니다

헷갈리기 쉬운 구분입니다. 프로젝트 지시문 파일은 시스템 지시문을 건드리지 않습니다. 그 내용은 대화 쪽으로 주입돼요. 그래서 어떤 지시문 설정을 골랐든 나란히 함께 동작합니다.

덕분에 이점이 하나 더 생깁니다 — 그 파일 내용은 지시문 재사용에 영향을 주지 않아요. 팀마다 규칙이 달라도 캐시는 공유되는 거죠. 다만 불러올 출처를 비워두면 이 파일도 안 읽힙니다. 출처를 껐는데도 읽히는 것들이 따로 있는 것과 헷갈리지 마세요 — 이건 확실히 안 읽힙니다.

🛡️ 지시문 밖에서 거는 방어도 함께 봐야 합니다

안전 지시가 빠지지 않게 챙기는 건 지시문 안쪽 이야기인데, 지시문 밖에서 거는 방어도 함께 쌓아야 합니다. 코드 폴더를 읽기 전용으로 붙여도 그 안의 설정 파일과 클라우드 자격증명은 그대로 읽혀요. "못 고친다"와 "못 본다"는 다른 얘기라, 통째로 붙이지 말고 필요한 것만 골라 담아야 합니다.

자주 묻는 질문 (FAQ)

Q. 페르소나를 저장해두고 재사용하려면?

출력 스타일이라는 파일 방식이 있습니다. 개인용 폴더에 두면 모든 프로젝트에서, 저장소 안에 두면 팀과 함께 쓸 수 있어요. 여기에 함정이 하나 있는데 — 직접 만든 출력 스타일은 기본 묶음의 소프트웨어 개발 지시를 빼고 내 것으로 대체합니다. 코드 리뷰처럼 여전히 개발 작업을 하는 역할이라면 그 지시를 남기는 표시를 앞머리에 적어 두세요. 역할을 통째로 바꿀 때만 빼는 게 맞습니다. 참고로 파이썬 쪽에서는 이걸 코드로 고르는 방법이 없어서, 파일을 못 쓰는 환경이면 덧붙이기를 쓰세요.

Q. 긴 지시문을 넘겼더니 실행 자체가 안 됩니다.

명령줄 인자 길이 한계에 걸린 겁니다. 파이썬 쪽은 문자열로 넘긴 지시문을 그대로 하나의 명령줄 인자로 실어 보내는데, 운영체제마다 한계가 있어요. 넘으면 요청이 나가기도 전에 프로세스 띄우기 단계에서 실패합니다. 해결은 간단한데 문자열 대신 파일로 넘기는 방식이 따로 있습니다. 긴 지시문을 쓸 계획이면 처음부터 그쪽으로 가세요.

Q. 어떤 경우에 직접 써야 하나요?

문서가 네 가지로 정리합니다. 결과를 읽는 자리가 터미널이 아닐 때(채팅 화면이나 자동 처리), 스스로를 코딩 도구로 소개하면 안 될 때(고객 상담 봇 같은), 사람이 매 단계를 승인하지 않고 혼자 도는 구조일 때, 그리고 코딩이 아닌 일을 할 때입니다. 마지막이 특히 중요한데 — 기본 묶음의 대부분이 코딩 안내라서, 조사나 문서 작업 에이전트에게는 그게 내가 진짜 원하는 지시와 경쟁합니다. 반대로 사람이 안 보는 자동 코딩 작업은 여전히 기본 묶음이 맞습니다.

🧾 정직하게 밝혀둘 것

• 제가 지시문을 갈아끼워 비교해본 실측이 아닙니다. 공식 문서의 구분·비교표·주의 사항을 우리말로 정리했습니다.
• ★설정 항목 이름·환경 변수·파일 경로·판올림 번호는 옮기지 않았습니다. 실제로 설정할 때는 원문 표를 보세요.
• ★"모르고 빠뜨리는 것과 알고 감수하는 것은 다르다"는 제 정리이고, 문서는 각 방식이 무엇을 남기는지만 밝힙니다.
• 기본값과 지원 범위는 판올림마다 바뀔 수 있습니다. 2026년 8월 기준입니다.

✨ 정리하면

아무것도 안 적으면 도구 호출만 다루는 최소한이 붙고, 안전 지시와 환경 정보는 빠집니다. 게다가 터미널에서 돌릴 때와 기본값이 달라 옮겨오면 동작이 바뀌어요. 통째로 새로 쓰면 도구 안내와 안전 지시를 내가 다시 채워야 하니, 기본 묶음에 덧붙이는 방식이 가장 안전합니다. 캐시가 안 맞는다면 폴더 같은 환경 정보가 지시문에 박혀 있기 때문이고요. 설정이 어디까지 읽히는지는 설정 불러오기 정리, 하위에 일을 맡길 때 따라가는 것은 하위 에이전트 정리, 안전 지시를 덜어낸 모델 이야기는 Hermes 오픈소스 LLM, 전체 비용 흐름은 AI 지출 관리 허브에 모아뒀습니다.

※ 출처: Claude 에이전트 개발 도구의 시스템 지시문 공식 문서(2026년 8월 31일 열람). 기본값은 판올림마다 달라질 수 있습니다.