2026 딥시크 하니스 AGENTS.md 미작동 점검법

딥시크 하니스 AGENTS.md 미작동은 파일 내용을 계속 늘리기보다 세션 작업 폴더와 프로젝트 루트 인식 결과를 먼저 확인한 뒤, 후보 파일과 내용 제한을 점검하고 새 세션에서 다시 검증하면 가장 빠르게 해결됩니다. 이 순서는 로컬과 원격 환경 모두에 적용됩니다.

이미 AGENTS.md를 만들었지만 에이전트가 프로젝트 규칙을 무시하는 개발자에게 필요한 글입니다. 여러 폴더와 저장소를 관리하는 기술 책임자, 원격 맥으로 작업 환경을 옮긴 뒤 동작이 달라진 운영 담당자도 대상입니다.

파일은 있는데 왜 규칙이 적용되지 않을까요?

대표적인 실패는 파일이 없어서가 아닙니다. 파일이 있어도 다음 조건 중 하나가 맞지 않으면 새 세션의 workspace context에 들어가지 않을 수 있습니다.

• 실행한 터미널의 현재 폴더와 웹 화면에서 선택한 작업 공간이 다릅니다.
• 하니스가 판단한 프로젝트 루트가 실제 저장소 루트와 다릅니다.
• 저장소의 상위 폴더에 있는 규칙이 다른 프로젝트의 규칙과 섞입니다.
• AGENTS.md, CLAUDE.md, 전역 지시 파일이 동시에 후보가 되면서 내용이 접히거나 충돌합니다.
• 파일이 너무 크거나 인코딩과 줄바꿈 형식이 비정상적이어서 읽기 단계에서 제외됩니다.
• 파일을 수정했지만 기존 세션이 예전 컨텍스트를 계속 사용합니다.
• 원격 맥에서 저장소 경로와 홈 디렉터리, 권한이 로컬과 달라집니다.

첫 번째 확인은 “파일이 존재하는가”가 아니라 “현재 세션이 어떤 경로를 기준으로 후보를 만들었는가”입니다. 공식 저장소의 하니스 구조와 명령행 실행 방식도 작업 폴더를 별도 입력으로 취급하므로, 실행 위치는 결과에 직접 영향을 줄 수 있습니다. 공식 저장소의 실행 및 구성 설명

주의: 기본 후보 순서, 파일 변경 감시, 화면에 표시되는 로딩 상태는 설치 버전에 따라 달라질 수 있습니다. 확인하지 않은 기본값을 팀 문서에 고정하지 마십시오.

세션을 만들기 전에 경로를 고정하십시오

다음 세 가지를 같은 기록에 남기면 경로 오류를 빠르게 분리할 수 있습니다.

1. dsh를 실행한 터미널의 현재 폴더를 기록합니다.
2. 웹 화면에서 선택한 작업 공간의 이름과 경로를 기록합니다.
3. 실제 저장소 루트에서 버전 관리 폴더나 프로젝트 설정 파일이 있는지 확인합니다.

예를 들어 터미널은 /작업/결제앱을 가리키지만 웹 화면은 /작업을 작업 공간으로 잡고 있을 수 있습니다. 이때 하니스는 의도한 저장소가 아닌 상위 폴더를 프로젝트로 판단할 수 있습니다. 반대로 모노레포 안에서 /작업/서비스에이를 열었는데 루트 표식이 상위 모노레포에만 있다면, 에이전트가 예상보다 넓은 규칙 집합을 읽을 가능성도 있습니다.

최소 테스트 저장소를 만들어 업무 코드의 영향을 제거하십시오.

• 루트에 짧은 AGENTS.md만 둡니다.
• “파일을 수정하지 말고 응답 첫 줄에 검증용 문구를 표시한다”처럼 위험이 없는 규칙을 넣습니다.
• 루트에서 새 세션을 만듭니다.
• 하위 폴더에서 다시 새 세션을 만듭니다.
• 두 응답의 검증용 문구와 작업 경로 인식을 비교합니다.

이 테스트에서조차 규칙이 반영되지 않으면 업무 저장소의 복잡한 지시가 아니라 경로, 후보 탐색, 구성 문제일 가능성이 높습니다.

첫 로딩에서 후보 파일을 증명하는 방법

전역 지시, 프로젝트 지시, 하위 폴더의 덮어쓰기 파일을 구분해 실제 위치를 표로 적으십시오. 파일명만 확인하지 말고 후보가 만들어지는 순서와 현재 세션에 들어온 여부를 관찰해야 합니다.

검증용 규칙은 실제 업무 명령과 분리해야 합니다. 예를 들어 자동 배포나 대량 삭제를 지시하는 문장을 테스트용으로 사용하면, 로딩 여부를 확인하는 과정 자체가 위험해집니다. 읽기 전용 응답, 특정 파일을 열지 말라는 제한, 변경 전 확인을 요구하는 문장이 적합합니다.

AGENTS.md는 사람을 위한 설명서보다 에이전트가 재현해야 할 명령과 경계에 집중하는 편이 좋습니다. 일반적인 저장소 문서와 에이전트 지시를 분리하는 설계 원칙은 AGENTS.md의 역할을 설명하는 기술 자료에서도 확인할 수 있습니다.

하위 폴더와 여러 지시 파일을 비교하십시오

모노레포에서는 루트 세션과 하위 프로젝트 세션의 규칙 집합이 같다고 가정하면 안 됩니다. 다음 순서로 비교하십시오.

1. 저장소 루트에서 새 세션을 만듭니다.
2. 현재 작업 폴더와 적용된 고유 규칙을 확인합니다.
3. 하위 서비스 폴더로 이동합니다.
4. 기존 세션을 이어 가지 말고 새 세션을 생성합니다.
5. 같은 기준 작업을 요청해 응답 차이를 저장합니다.
6. 루트의 AGENTS.md와 하위 폴더의 AGENTS.md가 각각 어떤 범위를 의도하는지 대조합니다.

동일한 문장이 여러 파일에 반복되면 화면이나 내부 컨텍스트에서 접혀 하나처럼 보일 수 있습니다. 반대로 파일 내용은 비슷하지만 경로가 다른 경우에는 전혀 다른 프로젝트의 규칙이 들어올 수 있습니다. 따라서 “규칙이 보였다”는 신호만으로 올바른 파일이 적용됐다고 판단하지 말고, 파일마다 서로 다른 검증 문장을 임시로 사용하십시오.

AGENTS.md와 CLAUDE.md를 함께 운용한다면 책임을 나누는 편이 안전합니다. 저장소 전체의 빌드와 테스트 규칙은 프로젝트 파일에, 특정 도구에서만 필요한 실행 방식은 도구별 파일에 두십시오. 같은 규칙을 두 파일에 복사하면 한쪽만 수정된 뒤 오래된 지시가 다시 나타나는 문제가 생깁니다.

내용 제한과 형식 문제를 먼저 분리하십시오

지시 파일이 크다고 해서 규칙이 더 잘 적용되는 것은 아닙니다. 공식 구성에서 내용 예산이나 컨텍스트 예산을 지원하더라도, 이 글에서는 확인되지 않은 고정 바이트 수나 고정 토큰 수를 제시하지 않습니다. 버전과 실행 방식에 따라 실제 경계가 달라질 수 있기 때문입니다. 컨텍스트와 요청 한도를 다루는 구현 자료를 기준으로 현재 설치 버전을 확인하십시오.

점검할 항목은 다음과 같습니다.

• 파일이 일반 텍스트로 읽히는지 확인합니다.
• 이름의 대소문자와 확장자가 정확한지 확인합니다.
• 비정상적인 인코딩, 제어 문자, 깨진 줄바꿈을 제거합니다.
• 긴 배경 설명과 반드시 지켜야 할 실행 규칙을 별도 파일이나 문서로 나눕니다.
• 규칙을 절반 이하로 줄인 최소본을 새 세션에서 시험합니다.
• 최소본이 적용되면 내용을 한 묶음씩 되돌리며 무시되는 경계를 찾습니다.

긴 지시 파일에 설계 배경, 회의 기록, 예외 사례를 모두 넣으면 실제 실행 규칙이 뒤로 밀릴 수 있습니다. 핵심 규칙은 짧고 검증 가능하게 유지하고, 배경 자료는 작업 요청이나 별도 문서에서 필요할 때만 불러오십시오. 컨텍스트가 커지는 문제를 해결하려고 지시 파일을 무한히 늘리는 방식은 권장하지 않습니다.

파일을 고친 뒤 세션을 구분해서 시험하십시오

파일 변경 후에는 최소 세 조건을 따로 비교해야 합니다.

• 기존 세션 계속하기: 이전 지시가 유지되는지 확인합니다.
• 새 세션 만들기: 수정한 파일이 첫 로딩에 반영되는지 확인합니다.
• 실행 프로세스 재시작: 구성 캐시나 환경 변수까지 새로 읽히는지 확인합니다.

각 시험에서 같은 기준 작업을 사용하고, 다음 자료를 남기십시오.

• 수정 전 파일의 내용 또는 해시
• 수정 후 파일의 내용 또는 해시
• 세션을 만든 시각
• 작업 폴더와 프로젝트 루트
• 에이전트의 검증 가능한 응답
• 실제 파일 변경 여부

기존 세션이 계속 예전 규칙을 따른다고 해서 파일 감시 기능이 고장 났다고 단정하지 마십시오. 대화 기록에 이미 들어간 지시가 이후 응답에 영향을 주는 경우가 있기 때문입니다. 반대로 새 세션에서도 오래된 규칙이 나타난다면 전역 파일, 다른 프로젝트의 상위 파일, 원격 홈 디렉터리를 다시 확인해야 합니다.

다음 체크리스트를 순서대로 통과시키면 재현 가능한 인수 기준으로 사용할 수 있습니다.

• [ ] 터미널의 현재 폴더를 저장했습니다.
• [ ] 웹 작업 공간의 실제 경로를 확인했습니다.
• [ ] 하니스가 인식한 프로젝트 루트를 기록했습니다.
• [ ] 루트 표식이 의도하지 않은 상위 탐색을 막는지 확인했습니다.
• [ ] 전역, 프로젝트, 하위 폴더의 후보 파일을 분리했습니다.
• [ ] AGENTS.md와 CLAUDE.md의 역할이 겹치지 않게 정리했습니다.
• [ ] 파일 인코딩과 읽기 권한을 확인했습니다.
• [ ] 긴 배경 자료를 실행 규칙에서 분리했습니다.
• [ ] 기존 세션과 새 세션의 응답을 비교했습니다.
• [ ] 프로세스 재시작 뒤 같은 기준 작업을 반복했습니다.

원격 맥으로 옮긴 뒤에는 무엇을 다시 확인해야 할까요?

원격 실행 후 프로젝트 지시가 사라졌다면 프롬프트를 다시 쓰기 전에 환경 전달을 확인하십시오. 로컬에서의 홈 디렉터리와 원격 맥의 홈 디렉터리가 다를 수 있고, 저장소가 복제된 위치도 달라질 수 있습니다. DSH_HOME이 설정되어 있다면 실제 값과 그 안의 전역 지시 파일 위치를 기록해야 합니다.

또한 다음 차이가 자주 발생합니다.

• 파일은 복제됐지만 현재 사용자가 읽을 권한이 없습니다.
• 대소문자를 구분하는 파일 시스템에서 이름이 달라졌습니다.
• 웹 작업 공간은 원격 저장소를 가리키지만 터미널은 다른 복제본을 가리킵니다.
• 재시작 과정에서 사용자 환경 변수가 로딩되지 않았습니다.
• 기존 세션이 로컬에서 생성된 컨텍스트를 계속 보유합니다.

로컬과 원격에서 같은 최소 테스트 저장소를 사용하고, 같은 기준 작업을 새 세션에서 실행하십시오. 결과가 다르면 규칙 문장보다 경로와 환경을 비교해야 합니다. 원격 맥 개발 환경의 사용 사례는 원격 개발 환경 활용 안내에서 함께 확인할 수 있습니다. 작업 공간을 여러 프로젝트로 나누어야 한다면 다중 프로젝트 작업 공간 운영 기준도 참고할 수 있습니다.

복구되지 않을 때는 기존 세션을 폐기하고, 고정된 임시 폴더에 저장소를 다시 배치한 뒤, 최소 규칙만 넣은 깨끗한 세션을 만드십시오. 이 단계에서도 실패하면 지시 파일 작성 문제가 아니라 설치 버전의 로더 또는 환경 구성 문제로 분류해 공식 구성 문서와 소스 변경을 대조해야 합니다. 공식 구성과 소스 확인 자료를 기준으로 재검증하십시오. API 연결과 설치 버전의 공식 안내도 DeepSeek 공식 개발자 문서에서 함께 확인할 수 있습니다.

현재 개발 환경과 원격 맥을 어떻게 비교할까요?

로컬 환경은 이미 경로와 권한이 맞춰져 있어 빠르게 시작할 수 있지만, 팀원이 같은 규칙을 재현하기 어렵고 운영자가 직접 환경 차이를 추적해야 합니다. 반대로 원격 맥은 작업 공간을 고정하기 쉽지만, 파일 전달, 홈 경로, 권한, 세션 재생성 절차가 준비되지 않으면 규칙이 사라진 것처럼 보일 수 있습니다.

이 문제를 확인한 뒤에도 로컬 환경을 계속 유지할지는 작업 성격으로 판단하십시오. 장기간 같은 저장소에서 무거운 작업을 계속하고 물리 장치나 로컬 주변 기기가 필요하다면 직접 보유한 맥이 더 적합할 수 있습니다. 반면 단기 검증, 팀별 격리, 원격 접근, 새 세션 기준의 반복 시험이 필요하다면 KVMFLUX의 원격 맥 환경이 경로와 권한을 인수 기준으로 관리하기에 유리합니다.

특히 현재 환경에서 작업 공간이 자주 바뀌거나, 재부팅 뒤 환경 변수가 사라지거나, 팀원이 서로 다른 저장소 복제본을 사용한다면 프롬프트를 고치는 것보다 실행 환경을 표준화하는 편이 낫습니다. 필요한 경우 원격 맥 환경 신청 안내에서 작업 방식에 맞는 전달 조건을 확인하십시오.

자주 묻는 질문