서론

이전에 새로운 프로젝트에 참여할 때, 캐치업(Catch-up)을 위해 AI를 사용한 적이 있습니다.

"이 리포지토리(Repository)를 읽고 아키텍처(Architecture)를 정리해줘"라고 가볍게 부탁했더니, 그럴듯한 리포트가 생각보다 빨리 나왔습니다.

하지만 실제로 읽어보니

"ECS로 백엔드를 구동하고 있습니다"

여기서 끝났습니다.

아니, 그건 알고 있습니다.

내가 듣고 싶은 건 "그럼 어떻게 구동되는가?"라는 부분입니다. ALB를 경유하는지, 보안 그룹(Security Group)은 어떻게 제한되어 있는지, 그 부분을 전혀 알 수 없어서 원하는 정보에 도달할 수 없었습니다.

읽은 것 같기는 한데, 다음 작업으로 넘어갈 수 있을 정도의 구체성이 전혀 없습니다.

이번에 저 자신을 위해 "프로젝트 캐치업"을 돕는 Claude Code Skill을 만드는 과정에서, 이 "그럴듯하기만 한" 문제에 대한 저만의 해결책이 보였기에 정리해 두려고 합니다.

왜 추상적이 되어버리는가?

조금 생각해 본 결과, 이것은 AI가 게으름을 피우는 것이라기보다, "어느 정도의 구체성으로 작성해야 하는가"를 아무도 지정하지 않았기 때문이라고 느꼈습니다.

"아키텍처를 정리해줘"라는 지시만으로는, AI 입장에서 "ECS로 구동됩니다"도 "ALB→ECS→Aurora의 흐름이며, 보안 그룹이~"도 똑같이 "정리"로서 정답이 될 수 있습니다.

즉, 추상과 구체 중 어느 쪽으로 답해야 할지에 대한 판단을 AI에게 맡겨두었던 것이 근본 원인이었습니다.

"그렇다면 그 판단을 이쪽에서 구속해버리면 된다"

여러 가지를 시도하고 조사한 결과, 위 내용이 이번에 도달한 발상입니다. (솔직히 너무 구체적으로 쓰는 것은 번거롭기 때문에, "이런 내용을 쓰고 싶은데, 구체적인 예를 들어줘"와 같이 AI에게 지시할 문장을 AI가 생성하게 만드는 방식을 사용하고 있습니다)

"좋은 예·나쁜 예"로 구체성의 레벨을 구속하기

실제로 사용 중인 나쁜 예·좋은 예

한 일은 사실 심플합니다. Skill의 지시문(Instruction) 안에 "이 정도 레벨로는 불충분함", "이 정도 레벨까지 작성함"이라는 대비를 실제 문장 형태로 그대로 심어 넣었습니다.

예를 들어 DB 설계(DB Design)를 설명하게 하는 파트에서는 다음과 같이 해보았습니다.

나쁜 예 (너무 추상적임):

"
Member 테이블은 멤버 정보를 관리합니다."

좋은 예 (이 정도 레벨까지 요구함):

"
Member 테이블은 조직에 소속된 사용자 1명을 나타내며, role 컬럼으로 MANAGER/USER를 구분합니다. MANAGER는 조직 멤버 초대·삭제가 가능하고, USER는 열람·조작만 가능합니다. 로그인은 Cognito가 담당하고 있으며, Cognito의 사용자명과 Member.email을 대조하여 프로필을 불러오는 설계입니다."

마찬가지로 인프라 구성 설명 파트에도 이 대비를 넣었습니다.

나쁜 예:

"ECS로 백엔드를 구동하고 있습니다"

좋은 예:

"ECS Fargate로 백엔드 컨테이너를 구동하고 있습니다. ALB(Load Balancer)→ECS(Container)→Aurora(DB)라는 흐름으로 요청이 흐르며, ECS의 보안 그룹(Security Group)은 ALB로부터의 통신만 허용하기 때문에 ECS에 직접 액세스할 수는 없습니다."

왜 이 구속 방식이 효과적인가

"구체적으로 써줘"라고 한마디 부탁하는 것보다, 이렇게 "여기까지는 불충분하다"라는 하한선을 실례로 보여주는 것이 압도적으로 효과적이라는 것을 실감했습니다.

솔직히 이것은 이론적으로 알고 있었다기보다, 실제로 사용해 보고 나서 나중에 깨달은 부분이기도 합니다.

추상적인 지시는 해석의 여지가 크지만, 나쁜 예 그 자체를 보여주면 "아, 이 정도로는 안 되는구나"라는 라인이 정확하게 전달되는 느낌이 있었습니다.

나아가 Skill의 서두에는 "리포트를 다 읽은 후, 마치 자신이 그 프로젝트의 구현자인 것처럼 행동할 수 있는 수준의 이해를 제공할 것"이라는 목표(Goal)도 명시했습니다.

추상적인 "제대로 써줘"가 아니라, "읽은 후에 무엇을 할 수 있어야 하는가"라는 도달점 그 자체를 언어화했습니다. 그렇게 함으로써 AI가 스스로 "이 정도 구체적으로 쓰지 않으면 목표에 도달할 수 없겠구나"라고 판단할 수 있게 된 느낌이 있습니다.

문장만으로는 부족하다 ── 도표를 필수화한 설계 판단

mermaid 도표·ASCII 도표를 필수화한 이유

좋은 예를 심어 넣은 후에도 아직 한 가지 걸리는 부분이 있었습니다.

테이블 간의 관계나, 요청이 어떤 가드(Guard)·컨트롤러(Controller)·서비스(Service)를 통과하는지와 같은 "흐름"은 문장으로 아무리 구체적으로 써도 솔직히 읽기가 어렵습니다.

글은 기본적으로 위에서 아래로 읽기 때문에, 분기(Branch)나 의존 관계(Dependency)를 표현하기에는 적합하지 않다고 생각합니다.

그래서 문장의 밀도를 아무리 높여도 한계가 있어, 표현 형식 자체를 바꿔야 한다고 생각했습니다.

따라서 그러한 "흐름"이나 "관계"를 다루는 파트에서는, mermaid나 ASCII art를 통한 출력을 필수로 설정했습니다. 문장만으로 끝내는 것을 허용하지 않는 설계로 만든 것입니다.

실제 출력 예시

예를 들어, 요청(Request)이 어떻게 처리되는지는 다음과 같은 도표로 출력하게 하고 있습니다.

HTTP 리퀘스트 (Request)
│
▼
...

테이블 간의 연관 관계는 mermaid의 ER 다이어그램(ER Diagram)으로 출력하게 합니다.

이를 보고 "당연한 것 아닌가"라고 생각하실 수도 있지만, 포인트는 "도표로 그려라"가 아니라 "이 종류의 정보는 도표가 아니면 출력을 인정하지 않겠다" 수준까지 깊게 파고들어 지시하는 것이었습니다.

"문장이든 도표든 상관없으니 알기 쉽게"라고 하면, 결국 AI는 편한 쪽(문장)을 선택하기 쉽습니다.

이 사고방식은 다른 Skill에도 응용할 수 있습니다

지금까지의 이야기는 캐치업(Catch-up)용 Skill에 국한된 고안이 아니라, AI에게 무언가를 정리하게 하거나 설명하게 하는 타입의 Skill 전반에 응용할 수 있다고 느낍니다.

아직 모든 Skill에서 테스트해 본 것은 아니기에 어디까지나 감각적인 수준이지만, 정리하자면 제가 한 일은 딱 두 가지뿐입니다.

• "이것으로는 불충분하다"라는 나쁜 예시와, "이 정도까지 써주길 바란다"라는 좋은 예시를 지시문(Prompt) 안에 실물로서 포함시킨다.
• 문장으로는 표현하기 어려운 정보(흐름·관계·분기)는 도표 출력을 필수화한다.

둘 다 "더 구체적으로", "알기 쉽게"라는 추상적인 부탁을, 실례와 형식 지정이라는 구체적인 제약으로 치환한 것뿐입니다.

당연해 보이지만, Skill을 만들기 시작한 초기의 저는 이를 깨닫지 못하고 모호한 지시문만으로 만족하고 있었습니다.

요약

AI에게 무엇을 쓰게 할지 고민할 때, 자칫 "무엇을 시킬 것인가"에만 의식이 쏠리기 쉽지만, 실제로 효과가 있었던 것은 "어느 정도의 구체성으로, 어떤 형식으로 쓰게 할 것인가"까지 깊게 파고들어 설계하는 것이었습니다.

• 지시는 추상적인 부탁이 아니라, 실례로 보여준다.
• 문장으로 전달되지 않는 것은 형식 자체를 바꿔버린다.

이 두 가지를 의식하게 된 이후로, AI에게 무언가를 정리하게 할 때마다 느꼈던 "그럴듯하지만 쓸모는 없는" 답답함이 상당히 줄어든 느낌입니다. (기분 탓일지도 모르지만 지금은 그렇다고 치겠습니다)

그렇다고 해서 이것으로 "네! 완벽합니다!!"라고 할 수 있는 것은 아니며, 무언가 걸리는 부분이 있다면 점진적으로 개선하며 키워나가려 합니다.

이번 글이 누군가에게 도움이 되기를 바랍니다.

Discussion