서브 에이전트 불러오질 못함

Question

안녕하세요, 강사님. 완강을 목표로 열심히 수강 중인 수강생입니다. 강의를 들으면서 실제 프로젝트에 클로드 코드를 적용하는 방법을 배울 수 있어서 정말 많은 도움을 받고 있습니다. 친절히 알려주신 덕분에 현재 노션 견적서 프로젝트도 큰 어려움 없이 배포까지 진행할 수 있었습니다. 좋은 강의를 만들어주셔서 먼저 감사드립니다. 그런데 프로젝트를 진행하면서 총 8개의 서브 에이전트가 .claude/agents 에 저장되어 있는데, 실제 프로젝트에서는 한 번도 해당 서브 에이전트를 사용하지 못하고 있습니다. 최근 클로드 코드에서 에이전트 관련 명령어와 생성 방식이 변경된 것은 고지해주셔서 확인했습니다. 그래서 클로드에게 아래와 같이 요청해 보았습니다만 ".claude/agents에 저장된 md 파일을 읽고 서브 에이전트를 등록해줘" "현재 사용 가능한 서브 에이전트 목록을 확인해줘" 어떤 방법으로 요청해도 커스텀 서브 에이전트를 전혀 인식하지 못하고 있습니다. 제가 확인한 내용은 다음과 같습니다. 에이전트 파일 자체의 문제는 아닌 것으로 확인했습니다.(파일 위치 정상, 프론트매터 형식 정상, YAML 문법 오류 없음) 서브 에이전트 타입은 6개 고정(claude, claude-code-guide, explore, general-purpose, plan, statusline-setup) 클로드에게 이 현상에 대해 계속 질문해 보니, 아래와 같은 답변을 받았습니다. 이 방법을 어떻게 해결하면 좋을지 알고 싶습니다. 커스텀 서브 에이전트가 아니더라도 클로드 자체에서 강의와 비슷한 답변을 주어서 그대로 사용하였는데, 강의를 통해 배운 내용을 실제 프로젝트에서도 제대로 적용해 보고 싶어 짚고 넘어가고 싶었습니다. 혹시 저와 같은 증상을 겪고 있는 다른 수강생분들도 계실 것 같아 질문드립니다. 확인된 사실 - 8개 파일 모두 frontmatter(name, description, model, color) 형식이 정상입니다. YAML 문법 오류 없음. - 그런데도 Agent 도구가 인식하는 서브에이전트 타입은 항상 claude, claude-code-guide, Explore, general-purpose, Plan, statusline-setup 6개로 고정되어 있습니다. 원인 추정 표준 Claude Code CLI라면 .claude/agents/*.md를 스캔해 subagent_type에 자동 등록하는 기능이 있지만, 지금 이 세션이 동작 중인 환경(오케스트레이션 계층에 "FleetView" 같은 명칭이 보이는 것으로 보아 표준 CLI와 다른 래퍼/호스팅 환경으로 보입니다)은 프로젝트 로컬 .claude/agents/ 디렉토리를 읽어 동적으로 서브에이전트 타입을 추가하지 않고, 고정된 6종 타입만 제공하는 것으로 보입니다. 이는 제가 도구 호출로 바꿀 수 있는 설정이 아닙니다. 대안 완전한 "등록"은 불가능하지만, 실질적으로 같은 효과를 내는 방법은 있습니다 — 앞서 development-planner에 했던 것처럼, 필요할 때마다 해당 .md 파일의 지침 전체를 general-purpose 에이전트(또는 제가 직접)에게 프롬프트로 전달해 그 페르소나로 동작시키는 방식입니다. 8개 전부 재사용 가능한 형태로 준비해 둘 수 있습니다. 클로드의 버전을 함께 보내준 결과, 아래와 같은 답변을 받을 수 있었습니다. 클로드의 버그인지, 아니면 제가 설정을 잘못한 부분이 있는 건지 강사님의 판단이 알고 싶습니다. 확인했습니다 — 이건 버전 문제가 아니라 Claude Code 자체의 알려진(장기간 미해결) 버그입니다. 조사 결과 - claude doctor가 보여준 2.1.225 → 2.1.226 업데이트는 "버그 수정 및 안정성 개선" 정도의 유지보수 릴리스로, 커스텀 에이전트 관련 수정 사항은 언급되지 않았습니다. - GitHub anthropics/claude-code 저장소에 .claude/agents/(프로젝트/사용자 스코프 모두) 내 커스텀 에이전트가 /agents 목록에도, Agent 도구의 subagent_type에도 인식되지 않는 문제가 여러 버전에 걸쳐 반복 보고되어 있습니다: - 공통 증상: 파일은 정상(형식 문제 아님)인데도 세션 시작 시 .claude/agents/를 스캔하는 로직 자체가 파일 기반 에이전트를 인식하지 못함. UI(/agents)로 그 자리에서 직접 만든 에이전트는 해당 세션 한정으로만 동작하고, 재시작하면 그마저 사라지는 사례도 보고됨. 즉, 지금 발견하신 현상은 로컬 설정 문제가 아니라 Claude Code의 알려진 버그와 정확히 일치합니다. 추가 supabase 이벤트 관리 앱 프로젝트를 시작하면서 만든 nextjs-supabase-fullstack-developer 서브 에이전트는 직접 클로드를 통해 제작하여서 그런지, @agent 명령어를 입력했을 때 목록에도 잘 나오고 정상적으로 호출됩니다.

gymcoding · Answer

안녕하세요! 🙂 먼저 클로드가 답한 "알려진 미해결 버그"는 정확한 진단이 아닐 가능성이 높아요. 가장 유력한 원인은 세션의 작업 디렉토리 입니다. 공식 문서에 따르면 프로젝트 서브 에이전트는 세션이 시작된 위치에서 위로 거슬러 올라가며 .claude/agents/ 를 찾습니다. 세션이 프로젝트 폴더 밖에서 시작되면 이 폴더는 스캔 대상에 아예 들어가지 않아요. 파일이 정상이어도 못 찾는 게 정상 동작입니다. 알려주신 6개 목록은 커스텀 에이전트가 0개 로드된 상태의 기본값 이라, 형식 문제가 아니라 스캔 자체가 안 됐다는 신호예요. 이 순서로 확인해 보세요. 터미널에서 프로젝트 루트로 cd 한 뒤 claude 실행 (VS Code 확장이나 백그라운드 말고 순수 터미널로) 프롬프트에 @ 만 입력 → 자동완성에 8개가 뜨면 정상입니다. 가장 확실한 확인 방법이에요 안 뜨면 /doctor 실행 → name 값이 중복되면 하나만 로드되는데, 여기서 잡아줍니다 그래도 안 되면 .claude/settings.json 의 permissions.deny 에 Agent(...) 가 있는지 확인 참고로 시도하신 "md 파일을 읽고 등록해줘" 는 원래 동작하지 않는 방식이에요. 등록은 대화가 아니라 클로드 코드가 폴더를 스캔해서 처리하거든요. "목록 확인해줘" 도 클로드는 자기 도구에 정의된 것만 보고 답하기 때문에 계속 6개만 말합니다. 이번 케이스가 강의에서 강조드린 부분과 맞닿아 있어요. 클로드가 자기 실행 환경 을 설명할 때는 추측이 섞이기 쉽습니다. 단정적으로 답할수록 공식 문서로 한 번 교차 확인해 보시는 걸 권해드려요. 위 순서로 확인해 보시고, 그래도 안 되면 pwd 결과와 에이전트 파일 프론트매터를 남겨주세요. 바로 봐드리겠습니다. 감사합니다 🙏

communityai8509 · Answer

안녕하세요, 인프런 AI 인턴입니다. qpalkim님. 서브 에이전트의 인식 문제로 어려움을 겪고 계신 것에 대해 이해합니다. 상황이 다소 복잡할 수 있어, 여러 가능성을 고려해 봤습니다. 문제의 원인과 개선 방안 1. 에이전트 인식 문제 우선, .claude/agents 에 저장된 커스텀 서브 에이전트가 인식되지 않는 문제는 Claude Code의 알려진 버그일 가능성이 큽니다. 이 버그는 특히 점진적 업데이트 상황에서도 여전히 해결되지 않은 문제로, 사용자들로부터 꾸준히 보고된 내용입니다. 2. 청취 및 롤백 클로드의 기본적인 &ldquo;등록&rdquo; 시스템이 동작하지 않을 때는, 사용자가 이미 확인한 방법처럼 .md 파일의 내용을 직접 프롬프트로 전달하여 에이전트를 작동시키는 대안적 접근이 필요합니다. 이 과정을 통해 필요할 때마다 해당 에이전트를 적극적으로 활용할 수 있습니다. 3. 추가적인 설정 및 확인 사항 업데이트 확인 : Claude Code의 최신 버전으로 업데이트가 되어 있는지, 모든 라이브러리가 최신 상태인지 확인 바랍니다. 환경 설정 확인 : 에이전트 구조와 클로드의 설정 파일을 재검토하여 호출 시 정확한 디렉토리가 사용되고 있는지 확인해 주세요. 대체 경로의 시도 : 임시로 UI에서 직접 에이전트를 생성하여 세션 내 구현·테스트 후, 별도로 서브 에이전트가 구현될 수 있는지를 시도해보는 방법도 있습니다. 참고 및 관련 질문 유사한 사례가 있는 질문과 해결 방안 내용을 참고하시길 추천드립니다. 서브 에이전트 생성하기 - 서브 에이전트 생성 및 폴더 위치에 대한 문제를 해결하는 방법을 설명하고 있습니다. 서브에이전트 인식이 안됩니다 - 서브에이전트 인식 문제와 명령어 사용 문제에 대한 정보를 제공하고 있습니다. 클로드 코드의 발전을 통한 기술적 문제는 곧 해결될 가능성이 높습니다. 따라서 GitHub의 관련 이슈를 지속적으로 모니터링하시고, 업데이트 된 최신 정보에 귀 기울여 주세요. 저는 질문자님의 이해를 돕고자 지식공유자님의 기존 답변을 참고하여 유사한 답변 링크를 추천해드리고 있습니다. 현재 베타 기능으로 답변이 만족스럽지 않을 수 있는 점 양해 부탁드립니다. 🙏 추가적으로 궁금한 점이 있으시면, 이어서 질문해 주세요. 곧 지식공유자께서 답변해 주실 것입니다.