DOCs와 스킬관련 PRD 폴더트리

Question

PRD 부분 파트를 거의 5번넘게봤는데.. 업데이트 전인거 같기도하고 github 코드보면, ai한테 물어보고 공식문서를 봐도 docs폴더에 관한 내용은 안보이더라구요. 코드를 깃헙소스를 봐도, agents/ 안데도 docs가 있고, 밖에도 docs가 있는데, 헷갈려서 . 루트 폴더의 docs는 그냥 예시로 강의자님이 만든 프로젝트 구조같기한데 맞는지는 모르겠네요. agents/ 안에 docs 파일 안에 md는 서브에이전트같은데 ? 현재 서브 에이전트를 만들면 docs안에 들어가는게 아니라 agents/폴더안에 바로 md 형태로 만들어지더라구요. 스킬같은 경우는 루트디렉토리에 skills안에 그 스킬 이름의 폴더명으로 안에 스킬.md로 찍히던데, subagent의 스킬은 agents 안에서 skill.md를 만들어서 작동하도록해주는걸까요? 개념을 확실히 잡고 개발하고 싶은데, 뭔가 애매하게 알고 있는거 같아서 여쭤봅니다. 그래서, 업데이트 전후로 비교해서 skills.md 방식때문에 그런것인지 물어봐도. 그 부분이 아니고 의도적 설계라고 나옵니다. 공식문서 폴더 디렉토리 best pratice도 보고 구글링도 해봣는데, docs관련해서는 안나와서요. 서브 에이전트도 그냥 만들어지는데 일부러 agents 안에 docs를 만들거나 dev폴더 만들어서 넣은건가요? 만약 그렇다면 그것도 제대로 작동하는건지. 여러번 돌려보고 찾아봐도 이 부분이 조금 헷갈립니다. 마지막으로, 하네스 엔지니어링은 subagent를 병렬로 돌리는것을 말하는거로 이해했는데, 명시적으로 서브에이전트를 활용하라고 안해도, 클로드가 본인이 서브에이전트돌리면서 할때가 있고 아닐때가있어서요. 이 부분을 다른 커뮤니티 물어봐도 다 이상하게 대답해서, 그래도 저자님이 생각하시는 것의 개념은 무엇일까요? 제미나이 기준은 아래와 같은데, 제가 생각하기에는 이렇게하면 하나의 ai에게 모두 일임하는거라서 agents. team만들어서 클로드 코덱스 재미니나 kimi이렇게 돌리면서 하는게 하네스가 아닐까하는생각도 드는데, 그러면 프로젝트 저 디렉토리(예전으로 치면 손코딩 폴더패턴 mvc패터니나 repositorty패턴이런 것처럼 규격화 말하는거 같다고 이해합니다.) 구조를 만들고, 거기에 다양한 ai모델로 돌리는게 맞을까요?

짐코딩 · Answer

안녕하세요 🙂 결론부터 말씀드리면 헷갈리신 부분 대부분은 정상 동작 이고, 잘못 이해하신 게 아니에요. 핵심만 정리해드릴게요. 먼저 폴더 구조요. 루트의 docs/ 는 클로드 코드 기능이 아니라 제가 프로젝트를 만들면서 둔 일반 폴더 예요. 추측하신 대로 맞고, 공식 문서에 안 나오는 게 당연합니다. agents/dev/ , agents/docs/ 도 서브에이전트를 분류하려고 만든 정리용 폴더 고요. 클로드 코드는 .claude/agents/ 를 재귀적으로 스캔 하기 때문에, 그 아래를 어떻게 나누든 동작엔 영향이 없어요. 서브에이전트는 폴더 경로가 아니라 파일 안의 name 값으로 인식되거든요. 그래서 폴더명은 편한 대로 지으셔도 됩니다. 그래서 /agents 로 만든 서브에이전트가 agents/ 바로 아래에 .md 로 생기는 것도 정상이에요. 분류 폴더로 정리하고 싶으면 그 파일을 agents/dev/ 안으로 옮기셔도 똑같이 작동합니다. 스킬과 서브에이전트는 아예 다른 기능 이라는 것도 짚어드릴게요. 스킬은 .claude/skills/<이름>/SKILL.md 에 두는 "필요할 때 불러오는 작업 매뉴얼"이고, 서브에이전트는 .claude/agents/<이름>.md 파일 하나(프론트매터 + 시스템 프롬프트)가 곧 "독립된 컨텍스트를 가진 일꾼"이에요. 그래서 "서브에이전트의 스킬을 agents 안에 SKILL.md로 만든다"는 구조는 아니에요. 둘은 사는 폴더도 역할도 다른 별개 메커니즘입니다. 마지막으로 하네스(harness) 가 핵심인데, 이건 서브에이전트를 병렬로 돌리는 것도, 여러 AI 모델(코덱스·제미나이 등)을 팀으로 묶는 것도 아니에요. 하네스의 본질은 한 줄로 "모델 자체가 아니라, 모델이 일할 '환경'을 설계하는 것" 이에요. CLAUDE.md(규칙), 스킬(반복 작업), 서브에이전트(역할 분리), 규칙 파일, 피드백 루프, 이 전체 구조가 하네스입니다. 같은 모델이어도 이 환경을 잘 설계하면 결과물이 확 달라지고요. "규격화된 디렉토리 구조를 만든다"고 이해하신 방향은 정확해요. 다만 여러 모델을 돌리는 것 자체가 하네스는 아니라는 것만 구분하시면 됩니다. (멀티 모델은 그 위에 얹는 선택일 뿐이에요.) 참고로 클로드가 서브에이전트를 알아서 돌릴 때도, 안 돌릴 때도 있는 건 정상이에요. 서브에이전트의 description 이 지금 작업과 맞아떨어질 때 자동으로 위임하기 때문이고, 확실히 쓰고 싶으면 "~~ 서브에이전트로 해줘"처럼 직접 지정하시면 됩니다. 이 부분은 강의 후반부에서 더 깊게 다루니 함께 보시면 개념이 더 또렷해지실 거예요. 또 막히는 부분 있으면 편하게 남겨주세요. 감사합니다 🙂

인프런 AI 인턴 · Answer

안녕하세요, 인프런 AI 인턴입니다. luke님. 강의에서 다룬 PRD 및 서브에이전트 관리에 관하여 혼란스러우신 것 같습니다. 강의 내의 설명이나 깃허브의 코드가 현재 업데이트된 코드 구조와 차이가 있음을 이해하고 계신 것 같습니다. 여러분의 이해를 돕기 위해 다음과 같이 요약하겠습니다: PRD와 Docs 폴더 구조 루트 폴더의 docs 폴더 : 일반적으로 프로젝트의 공식 문서 및 설명서를 포함하기 위한 폴더로 사용됩니다. 강의자님이 프로젝트 시나리오 예시로 설정한 것입니다. 주로 프로젝트 소개, 사용법 설명서 등이 포함될 수 있습니다. agents 폴더 내의 docs 폴더 : 서브에이전트를 정의하기 위한 폴더로 사용되며 .md 파일 형태로 서브에이전트 문서가 배치될 수 있습니다. 강의에 따라 서브에이전트 역할을 관리하고자 할 때의 위치입니다. .claude/agents 폴더 : 현재 클로드 코드는 업데이트로 인해 새로운 폴더 구조가 적용될 수 있습니다. 이 폴더 구조 내에서는 특정 기능을 수행하는 서브에이전트 문서를 포함할 수 있습니다. 생성된 파일은 프로젝트의 요구사항에 따라 위치시킬 수 있으며, .claude/agents 하위에 자체적으로 직접 생성하거나 관리하는 것이 적합합니다. 최근 업데이트 사항 서브에이전트가 docs 폴더 안에 들어가는 것이 아닌 agents 폴더 안에 바로 생성될 수 있다는 점은 클로드 코드의 업데이트나 개선사항에 따른 것이며, 의도적인 설계일 가능성이 높습니다. 추가적으로 도움이 될 수 있는 자료 관련 예제나 보다 구체적인 설명을 원하시면 강의 내 자료 및 커뮤니티에서 제공된 다른 사용자분들의 질문을 참고하실 수 있습니다. 서브에이전트 활용 및 관련 질문 게시글 에서 다양한 상황에 대한 답변을 참조하시면 도움이 되실 것입니다. 저는 질문자님의 이해를 돕고자 지식공유자님의 기존 답변을 참고하여 유사한 답변 링크를 추천해드리고 있습니다. 현재 베타 기능으로 답변이 만족스럽지 않을 수 있는 점 양해 부탁드립니다. 🙏 추가적으로 궁금한 점이 있으시면, 이어서 질문해 주세요. 곧 지식공유자께서 답변해 주실 것입니다.