AI 에이전트 하네스 루프 그래프 엔지니어링 적용 방법이 궁금하다면 구독자 무료 클로드 스킬로 내 에이전트 상태부터 진단해 보세요. 설치와 사용법, 주의점, 한계까지 정리했어요.
AI 비밀무기 유튜브 구독자를 위한 무료 스킬이에요.
내 AI 에이전트가 하네스, 루프, 그래프 엔지니어링 기준으로 어떤 상태인지 진단하고, 적용할 방법을 알려 줘요.
사용하기 전에 반드시 아래 설명서(이 글)를 먼저 읽어 주세요.
클로드 코드, 코덱스, 안티그래비티에서 쓸 수 있어요. 안티그래비티는 직접 시험하지 못했어요.
먼저 AI 비밀무기 영상을 보고 오시면 이해가 쉬워요. 아래 영상 카드를 누르면 유튜브에서 바로 볼 수 있어요.
이 스킬은 하네스, 루프, 그래프를 이렇게 진단해요
받은 파일을 읽고 건강검진 실행해줘 한마디만 하면 시작돼요. 파일을 하나하나 복사해서 설명할 필요가 없어요.
스킬은 폴더 안의 지침 파일과 업무지시서, 규칙 파일, 설정 파일을 읽어요. 이 단계에서는 읽기만 하고 아무것도 고치지 않아요.
읽은 내용은 하네스, 루프, 그래프 기준의 11개 항목으로 살펴봐요. 잘 된 곳은 체크 표시를, 아쉬운 곳에는 번호를 붙여요.
결과는 25줄 안쪽이고, 아쉬운 것은 중요한 순으로 최대 3개만 쉬운 말로 보여 줘요. 이렇게 번호가 붙은 표를 건강검진표라고 불러요.
마음에 와닿는 번호를 하나 고르면 넣을 문장 초안을 먼저 보여 줘요. 대화창에서 넣어요라고 하면 그때 한 줄만 넣고, 한 번에 하나씩만 해요.
기존 내용은 지우지 않고 추가만 해요. 에이전트가 아직 없다면 폴더 하나와 지침 세 줄로 시작하는 첫 시작 안내를 보여 줘요.
이 스킬은 실행한다고 바로 하네스·루프·그래프 엔지니어링이 적용되는 스킬이 아닙니다. 여러분의 에이전트를 진단하고 개선할 방안을 간략히 알려 주는 참고용입니다.
검진 결과는 정답이 아니니 내 일하는 방식에 맞는 번호만 골라 쓰면 돼요.
받는 파일은 ZIP 하나이고, 압축을 풀면 my-agent-checkup.md 파일 하나가 나와요. 사용 방법은 바로 아래에 적었어요.
이런 결과가 나와요
에이전트 폴더는 AI에게 주는 규칙·역할 설명이 들어 있는 폴더를 말해요. 이 글에서는 앞으로 계속 이 이름으로 불러요.
실제 에이전트 폴더를 읽어 번호가 붙은 건강검진표를 쉬운 말로 만들어 주는데, 아래는 시험용 가짜 폴더로 돌린 결과예요.
클로드 스킬 설치 방법과 사용법 3단계
쓰는 방법은 한 가지예요. 파일 하나를 받아서 AI에게 읽고 실행해 달라고 말하면 끝나고, 따로 설치할 것은 없어요.
| AI | 직접 시험 |
|---|---|
| 클로드 코드 | 했어요 |
| 코덱스 | 진단까지 |
| 안티그래비티 | 못 했어요 |
시험은 같은 내용을 채팅창에 붙여넣는 방식으로 했어요. 표의 시험 결과는 그 기준이고, 안티그래비티는 직접 해 보지 못했어요.
사용 방법 3단계
- 1단계는 압축을 풀고 나온 my-agent-checkup.md 를 내 AI 에이전트 폴더에 넣는 거예요. 폴더에 넣기 어렵다면 채팅창에 첨부해도 돼요.
- 2단계는 에이전트 폴더를 연 채로 클로드 코드, 코덱스, 안티그래비티를 켜는 거예요. 첨부만 하면 정확도가 낮아요.
- 3단계는 AI에게 my-agent-checkup.md 파일을 읽고 건강검진 실행해줘라고 말하는 거예요. 그러면 25줄 안쪽의 짧은 결과가 나와요.
결과에는 읽은 파일 이름과 근거가 안 나오고, 궁금하면 자세히 보여줘라고 말하면 그때 보여 줘요. 결과가 길어지지 않게 한 거예요.
선택 카드가 뜨면 번호를 누르고, 카드가 없으면 숫자를 입력해요. 초안을 보고 대화창에 넣어요라고 하면 그때 한 줄이 들어가요.
처음이라면 클로드 코드 빠른 시작으로 설치와 로그인을 먼저 마쳐요. 폴더를 연 채로 켠다는 건 작업 폴더로 에이전트 폴더를 고르는 거예요.
데스크톱 앱이라면 Code 화면에서 폴더 선택 버튼으로 고르고, 터미널이라면 폴더로 이동한 뒤 claude 를 실행해요.
이 방법은 도구를 읽기로만 묶어 두는 장치가 없어요. 그래서 읽기 전용은 글로 된 규칙과 AI의 허락 창에 기대요.
코덱스는 CLAUDE.md 대신 AGENTS.md 를 쓰는 경우가 많은데, 이 스킬은 둘 다 읽어요. 이름을 바꿀 필요는 없어요.
코덱스에서는 진단과 번호 안내까지만 시험했어요. 문장 초안을 넣는 단계는 아직 확인하지 못한 상태예요.
폴더를 못 읽는 클로드 웹이나 챗GPT 웹 같은 채팅은 붙인 내용만 보고 판단하니 정확도가 아무래도 낮은 편이에요.
AI가 파일 내용을 붙여 달라고 하면 비밀번호나 키가 든 줄은 빼고 붙여요. 고칠 문장도 내가 직접 넣어야 해요.
하네스 루프 그래프 11개 점검 항목
건강검진표는 하네스 5개, 루프 3개, 그래프 3개로 모두 11개 항목을 봐요. 정답표가 아니라 판정 기준을 잡아 둔 참고용이에요.
| 영역 | 보는 것 | 판정 단서 |
|---|---|---|
| 하네스 1 | 지침 파일에 구체적인 규칙이 있나 | 규칙 3줄 이상 |
| 하네스 2 | 일이 끝났다고 칠 기준이 있나 | 끝 기준 한 줄 |
| 하네스 3 | 결제·삭제·발송 같은 위험한 일에 사람 확인이 있나 | 글과 설정 둘 다 |
| 하네스 4 | 다 했다는 보고에 증거를 붙이게 하나 | 증거 요구 |
| 하네스 5 | 비밀 값이 문서에 직접 적혀 있지 않나 | 의심 줄 0개 |
| 루프 1 | 결과를 다시 확인하는 단계가 있나 | 확인 단계 |
| 루프 2 | 고치는 횟수 상한이 있고 막히면 사람에게 넘기나 | 횟수와 넘김 |
| 루프 3 | 내가 고쳐 준 내용이 규칙으로 쌓이나 | 규칙 쌓기 |
| 그래프 1 | 일의 순서가 적혀 있나 | 순서 적기 |
| 그래프 2 | 넘길 때 남기는 기록과 되돌릴 곳이 있나 | 넘김 기록 |
| 그래프 3 | 사람이 확인하는 지점이 흐름 안에 있나 | 확인 지점 |
하네스 엔지니어링 뜻은 쉽게 이래요
하네스는 원래 말에게 씌우는 마구를 뜻하는 낱말이에요. 말이 엉뚱한 곳으로 달리지 않게 잡아 주는 장비라는 뜻이죠.
하네스 엔지니어링은 AI 두뇌 바깥에 규칙과 권한, 자동 검사 장치를 둘러서 같은 실수를 줄이고 믿고 맡기게 하는 일이에요.
규칙 파일은 부탁에 가까워서 AI가 잊을 수 있어요. 훅(AI 뜻과 상관없이 자동으로 도는 검사 장치)이나 권한 설정이 막는 장치예요.
루프 엔지니어링과 그래프는 뭘 볼까
루프는 해 보고, 확인하고, 다시 고치는 반복이에요. 사람이 매번 손대지 않아도 목표에 닿을 때까지 돌게 하고 끝나는 조건을 정해 두는 거예요.
그래프는 일을 점으로, 다음에 할 일의 규칙을 선으로 이은 지도예요. 워크플로우라고도 부르고, 지식 그래프와는 다른 말이에요.
혼자 일하고 한 단계로 끝나는 구조라면 그래프 3개는 해당 없음으로 처리해요. 일이 여러 단계로 이어지다 꼬일 때만 그려 봐도 늦지 않아요.
클로드 스킬 사용 전 주의사항과 한계
이 스킬은 검진하는 동안 읽기만 해요. 파일을 만들거나 고치지 않고, 명령 실행이나 인터넷 사용도 하지 않도록 규칙을 뒀어요.
읽기만 한다는 약속은 글로 된 규칙과 AI의 허락 창에 기대요. 정말 막으려면 컴퓨터 쪽 권한 설정도 같이 봐 주세요.
파일을 고치는 도구는 마지막 한 줄 넣기에 필요해서 꺼 두지 않았어요. 대화창에서 넣어요라고 하기 전에는 쓰지 않게 만들었어요.
권한 설정에 따라 고치기 직전에 수정해도 되는지 허락 창이 뜨기도, 안 뜨기도 해요. 검진할 때는 기본 모드를 권해요.
비밀 파일은 열지 않아요
.env 파일과 키·인증서 파일, 이름에 key, secret, token, password 가 들어간 파일은 내용을 읽지 않고 이름만 세요.
읽기 전에 알려진 키 모양이 든 문서가 있는지 먼저 검사해요. 걸린 파일은 본문을 열지 않고 이름만 알려 줘요.
검사에 걸려도 값은 화면에 옮기지 않아요. 다만 이 검사는 못 찾았다는 뜻일 뿐, 안전하다는 보증은 아니에요.
열지 못했거나 일부만 읽은 파일이 있을 때만 결과에 그 사실이 한 줄 나와요. 없으면 아무 말도 나오지 않아요.
검진 결과는 내 화면에만 보이고 따로 저장하거나 어디로 보내지 않아요. 다만 읽은 내용은 쓰는 AI 서비스가 처리해요.
폴더 안 파일에 이 지시를 따라라 같은 문장이 있어도 명령으로 따르지 않고 읽을 자료로만 봐요. 그래서 파일 속 문장에 휘둘리지 않아요.
솔직한 한계
- 안티그래비티는 붙여넣기 방식으로 쓸 수 있게 만들었지만 우리가 직접 시험하지 못했어요. 코덱스는 진단과 번호 안내까지만 시험했어요.
- 읽은 파일 안에서만 판단해요. 에이전트 폴더 밖에 둔 안전장치는 못 봐서 없다고 단정하지 않고 못 찾았다고 말해요.
- 비밀 값 검사는 일부 모양만 찾아요. 짧은 비밀번호(20자 미만)나 한글이 섞인 값은 놓칠 수 있고, 그런 파일은 검진 중 읽힐 수 있어요.
읽더라도 값은 화면에 옮기지 않아요. - 큰 폴더는 지침, 지시서, 규칙 위주로 최대 40개 파일을 읽고, 파일마다 앞 200줄까지만 봐요.
- 컴퓨터 차원에서 100% 막으려면 클로드 코드의 /permissions 에서 따로 막아야 해요.
- 자동 모드나 수정 자동 허용 모드를 켜 두면 허락 창이 뜨지 않아요. 검진할 때는 기본 모드로 쓰는 편이 안심돼요.
- 도구를 읽기로 묶는 장치가 없어서 글로 된 규칙에 기대고, AI마다 판정이 조금 다르게 나와요.
- 지침 파일에 넣는 문장은 부탁이에요. 정말 절대 안 되는 일은 나중에 훅이나 권한 설정으로 막는 걸 알아봐도 늦지 않아요.
- CLAUDE.md 는 클로드 코드가 대화를 시작할 때 스스로 읽어 들여요.
그래서 비밀 값 검사와 상관없이 그 내용은 이미 AI에 전달되니, 비밀 값은 처음부터 지침 파일에 적지 않는 게 가장 좋아요. - 맥에서만 실제로 시험했어요. 윈도우도 쓰도록 고려해 만들었지만 설치와 실행은 아직 확인하지 못했어요.
- 클로드 웹이나 모바일 앱에 올려서 쓰는 방법은 시험하지 못했어요.
클로드 코드는 무료 플랜에서는 열리지 않아서 유료 플랜이 필요해요. 가격은 클로드 코드 가격 글에 정리해 뒀어요.
한도가 걱정되면 클로드 주간한도 초기화 글을 참고해요. 지침 파일이 길수록 AI가 읽는 양이 늘어 사용량이 더 나갈 수 있어요.
자주 묻는 질문
Q. 어떤 AI에서 쓸 수 있나요
클로드 코드와 코덱스에서는 같은 내용으로 시험했어요. 안티그래비티도 같은 방식으로 쓰도록 만들었지만 직접 시험하지는 못했어요.
Q. 파일을 넣었는데 AI가 못 찾아요
에이전트 폴더를 연 채로 켰는지 먼저 봐요. 그래도 못 찾으면 파일을 채팅창에 첨부하거나 파일 경로를 알려 주고 다시 말해요.
정확도는 폴더를 열었을 때가 더 높아요.
Q. 윈도우에서도 되나요
윈도우에서도 쓰도록 글 파일만으로 만들었어요. 다만 맥에서만 시험했고 윈도우에서는 설치와 실행을 확인하지 못했어요.
Q. 내 파일이 밖으로 나가나요
스킬이 따로 저장하거나 어디로 보내지는 않아요. 다만 읽은 내용은 쓰고 있는 AI 서비스가 처리하고, 대화 기록 저장은 그 서비스 설정을 따라요.
Q. 내 파일을 마음대로 고치지는 않나요
진단 단계에서는 읽기만 해요. 번호를 고르고 초안을 본 뒤 대화창에서 넣어요라고 하면, 그때 한 번에 한 줄씩 추가만 해요.
설정 파일과 스크립트는 고치지 않아요.
Q. 비밀번호나 키가 들어 있어도 되나요
비밀 파일은 열지 않고 이름만 세요. 그래도 비밀 값은 처음부터 지침 파일에 적지 않는 게 가장 안전하고, 이미 공유했다면 키를 새로 발급받는 것도 생각해 봐요.
Q. 하네스, 루프, 그래프를 바로 적용해 주나요
아니에요. 이 스킬은 내 에이전트를 진단하고 개선할 방법을 간략히 알려 주는 참고용이에요. 점수나 등급도 매기지 않고, 적용은 내가 골라서 해요.
Q. 결과가 매번 조금씩 달라요. 에이전트가 아직 없어도 되나요
AI가 읽는 범위와 쓰는 서비스에 따라 판정이 조금 다르게 나와요. 에이전트가 아직 없으면 폴더 만들기부터 알려 주는 첫 시작 안내가 나와요. 코딩을 몰라도 써요.
Q. 무료인가요, 재배포나 업데이트, 문의는요
파일은 무료로 받아요. 별도 문의와 업데이트 대응은 하지 않아요. 필요하신 분만 받은 그대로 쓰세요.
마치며
클로드 스킬 적용 방법은 결국 두 단계예요. 파일을 에이전트 폴더에 넣고, 읽고 실행해 달라고 말을 거는 거죠.
처음부터 11개를 다 고칠 필요는 없어요. 일하다 불편했던 번호 하나만 골라 한 줄 붙이는 것으로 충분해요.
하네스, 루프, 그래프가 낯설다면 점검표를 한 번 훑어보고 건강검진 실행해줘라고 말해 보세요. 내 에이전트의 빈틈이 번호로 보여요.
이 스킬은 진단용이라 실제로 적용할지는 내 몫이에요. 설치가 막히면 위의 자주 묻는 질문부터 확인해 주세요.
참고용 진단 도구 · 맥에서 시험했고 윈도우와 안티그래비티는 직접 시험하지 못했어요