## Intro - CLAUDE나 Antigravity, Codex, OpenCode 등등. 사용하는 AI Coding Agents는 다 달라도. 꼭 이 세계에 발을 들이면 듣게 되는 단어, 안하면 뒤쳐질 것 같아서 신경쓰이는 단어들이 있다. ~~(뭐가 이리 많어..🙃)~~ > [!note] > - CLAUDE.md(=AGENTS.md) ✅ > - Slash Commands ✅ > - SKILLS ✅ > - HOOKS > - Subagent > - Harness - 오늘은 이 중에서 위 3개만 먼저 살펴보자. 개념 설명은 Claude Code 위주로 하되, Antigravity 설정 방법 순으로 진행해본다. Antigravity는 OpenCode, Cursor 등 다른 AI Coding Agent들의 설정과 거의 똑같거나 아주 비슷하니 참고하시길 ✔
## 0. Token 🎟️ - 이미 알고 있겠지만, 왠만하면 모든 .md 파일들은 다 영어로 작성된다. 왜냐면 Token을 적게 사용하기 위해(=돈을 아끼기 위해)서다. - 영어를 사용하면 6토큰.
![스크린샷 2026-02-27 오전 7.59.06|400](https://pub-08bdc1f395e14377951ac0c9c22ba795.r2.dev/posts/user_38T3Ty5uKeRndW9PUwTFHGYZxwP/a74ztl3sv3g------------2026-02-27-------7.59.06.webp) - 같은 말을 한국어로 하면 12토큰!
![스크린샷 2026-02-27 오전 7.58.42|400](https://pub-08bdc1f395e14377951ac0c9c22ba795.r2.dev/posts/user_38T3Ty5uKeRndW9PUwTFHGYZxwP/yy604uywz1------------2026-02-27-------7.58.42.webp) - OpenAI의 [Tokenizer](https://platform.openai.com/tokenizer)에서 영어와 한국어를 같은 의미인 문장으로 비교를 해보면, 아래와 같이 한국어가 영어보다. 최소 1.5~2배 정도 토큰을 더 많이 사용하는 것을 확인할 수 있다. Token은 LLM이 '텍스트를 숫자로 변환해서 처리하기 위한 최소 단위'를 뜻한다. - 보통 LLM이 학습할 때, 학습 데이터에서 자주 같이 등장하는 문자 패턴을 하나의 토큰으로 묶어가면서 이해하는데, 영어의 학습데이터 양이 압도적으로 많다보니 영어는 비교적 큰 의미단위를 하나의 토큰으로 해석할 수 있는 반면, 한국어와 같은 외국어는 상대적으로 학습데이터가 작기 때문에 일어나는 현상이다. - 그래서 Commands, Skills, Hooks, 등 왠만한 .md 파일들이 영어로 적는 것이 실행될 때마다 사용될 토큰을 줄이는 방법이라는 것을 참고! ✔️
## 1. CLAUDE.md / AGENTS.md - CLAUDE.md / AGENTS.md는 `항상 로드되는 전역 컨텍스트`다. 그래서 **프로젝트/팀 간의 공통 규칙이 있다면 적어서 항상 예외가 없도록 인지시키거나, 정말 중요한 내용 위주로 적는 것이 좋다**. 안그러면 실제 명령할 내용과 상관없는 문장들이 Token 비용만 발생시키고 AI에게 혼동만 가중시켜 성능을 떨어뜨릴 뿐이다. - Antigravity에서는 GEMINI.md를 사용하는데, AGENTS.md로 사용해도 된다. - 보통 CLAUDE.md/AGENTS.md 는 어떤 프로젝트, 스펙을 사용하는지, 코드 스타일, 커맨드, 그리고 아키텍처, 중요한 점 등을 적어놓는다. 쉽게 말하면, - `What` - 어떤 스택을 사용해서 어떤 것을 만드는지 - `Why` - 이 프로젝트 안의 다른 파일들, 파일 구조는 왜 존재하는 것인지(Structure) - `How` - 작업을 할 때는 어떤 방식으로 작업을 해야만 하는 것인지를 적는다고 이해할 수 있겠다. - Next.js 프로젝트라고 했을 때 예시는 아래와 같다. ```markdown # Project: ShopFront Next.js 14 e-commerce application with App Router, Stripe payments, and Prisma ORM. ## Code Style - TypeScript strict mode, no `any` types - Use named exports, not default exports - CSS: Tailwind utility classes, no custom CSS files ## Commands - `npm run dev`: Start development server (port 3000) - `npm run test`: Run Jest tests - `npm run test:e2e`: Run Playwright end-to-end tests - `npm run lint`: ESLint check - `npm run db:migrate`: Run Prisma migrations ## Architecture - `/app`: Next.js App Router pages and layouts - `/components/ui`: Reusable UI components - `/lib`: Utilities and shared logic - `/prisma`: Database schema and migrations - `/app/api`: API routes ## Important Notes - NEVER commit .env files - The Stripe webhook handler in /app/api/webhooks/stripe must validate signatures - Product images are stored in Cloudinary, not locally - See @docs/authentication.md for auth flow details ```
### 파일 생성 위치 🗂️ - 전역/프로젝트 한정 여부에 따라 아래와 같이 나뉜다. ~/.claude/CLAUDE.md                        # 👈 전역
project-root/.claude/CLAUDE.md     # 👈 프로젝트 한정 ~/.agents/AGENTS.md                        # 👈 전역
project-root/.agents/AGENTS.md     # 👈 프로젝트 한정 ### CLAUDE.md가 위치하는 곳 (3단계)📍 - CLAUDE.md는 세 가지 레벨에서 작동하는데, 대부분의 튜토리얼이 제대로 다루지 않는 중요한 부분이다. `레벨 1: Global` — ~/.claude/CLAUDE.md - 모든 프로젝트에 공통으로 적용된다. 선호하는 코딩 스타일, 언어 설정, 항상 쓰는 도구 같은 개인 설정을 여기에 담는다. ✍️ `레벨 2: Project` — project/CLAUDE.md - 해당 저장소에서만 적용된다. 프로젝트 아키텍처, 코딩 컨벤션, 빌드 명령어 등을 담는다. Git으로 팀과 공유되는 파일이다. 🔄 `레벨 3: Folder` — project/src/CLAUDE.md - 특정 디렉토리 안에서만 적용된다. 세션 시작 시 전부 로드되는 게 아니라, Claude가 해당 디렉토리의 파일을 읽을 때 온디맨드로 로드된다. ✅ `우선순위`: - **Folder > Project > Global** 즉, 아래와 같이 이해하면 된다. ``` ~/.claude/CLAUDE.md → "JavaScript를 써라" project/CLAUDE.md → "TypeScript를 써라" ← 이 프로젝트에서는 이게 이김 project/src/CLAUDE.md → "strict mode를 켜라" ← 이 폴더에서는 이게 이김 ``` ![claudemd-example](https://pub-08bdc1f395e14377951ac0c9c22ba795.r2.dev/posts/user_38T3Ty5uKeRndW9PUwTFHGYZxwP/f8gbiqcjijg-claudemd-example.webp) - 예를 들어, Global 레벨에서 'Python을 써라'라고 해놓고 프로젝트 레벨에서 'JavaScript를 써라'라고 했으면 JavaScript를 쓸 것이다. - 이 개념은 Amp, Codex, Cursor, Devin, Factory, Gemini CLI 등등 AGENTS.md를 사용하는 곳이면 동일한데.. Antigravity만 1, 2단계 계층구조까지만 적용되고 3단계 레벨의 파일 기반 계층은 의미가 없다고 한다. ~~(일 좀해라 구글)~~
### CLAUDE.md Best Practices ✨ - CLAUDE.md or AGENTS.md를 어떻게 하면 가장 잘 쓰는 것인가에 대한 여러 가이드와 논문들이 있다. 그 중 사람들에게 26년 3월 현재 어느정도 받아들여지고 있다 생각되는 내용은 아래와 같다. #### `1. Less (instructions) is more.` 😌 - 가능하다면 500줄 이내(300자 이내가 Best)로 작성하는 것을 추천한다. 500줄 이상의 명령어는 오히려 성능을 떨어뜨릴 수 있다. - 500자가 넘어가기 시작하면, 시작부분과 끝부분만 기억하고 중간 내용은 기억을 못하는 'Lost in the Middle' 현상이 일어난다. #### `2. Progressive Disclosure` 🔄 - 모든 정보를 CLAUDE.md에 적지 말고 필요할 때 모델이 알아서 참고해서 메모리에 올릴 수 있도록 설계해라. - 예를들어, 아래와 같이 별도의 directory를 생성하고 지침들을 적은 뒤, CLAUDE.md에 어떤 상황에 어떤 파일을 봐라고만 거론하는 것이다. 그러면 AI가 필요할 때, 스스로 판단해서 읽을 수 있게하는 것이다. ```bash agent_docs/ |- building_the_project.md |- running_tests.md |- code_conventions.md |- service_architecture.md |- database_schema.md |- service_communication_patterns.md ``` - 즉, **AI에게 정보를 단계적으로 공개하는 방법**이다. #### `3. Agent is not a linter.` 🙅 - Typescript 에러나 빌드시 문제가 될 문법적인 에러들을 잡는 Linter와 formmaters. 이 기능을 AI에게 시키면, 특히 CLAUDE.md/AGENTS.md에 적어놓으면 쓸때없이 비싸게 기능을 쓰는 것이라는 말이다. - 이렇게 특정 기능에 특화된 툴들이 이미 많을 때는, CLAUDE.md에 적을 것이 아니라 다음으로 알아볼 Command를 설정하거나 다음 글에서 알아볼 Hooks로 설정해서 자동화하는 것이 좋다.
## 2. Slash Commands💂‍♀️ - Slash Commands는 그냥 `Commands`라고도 지칭한다. 미리 만들어 놓은 기능을 `/your_command` 명령으로 실행하게 만든 함수같은 것이다. #### Claude Code 1. 전역으로 항상 어떤 프로젝트든 기본적으로 쓰고 싶을 때는 `~/.claude/` 아래에 `commands`라는 이름의 명령어를 만든다. 프로젝트에서 사용할 때는 프로젝트 root path에 `.claude`라는 이름의 폴더를 만들고, 그 아래 `commands`라는 이름의 폴더를 만들면 된다. mkdir -p ~/.claude/commands mkdir project-root/.claude/commands - 그 다음은 Commands 폴더 아래에 `내가 만들고 싶은 스킬 이름.md` 파일을 만들기만 하면 끝! - 나는 이전 포스팅에서 설정한 Obsidian MCP를 활용해서, `/today` 라는 Command를 아래와 같이 만들어 보았다.
![스크린샷 2026-03-01 오전 10.36.23|700](https://pub-08bdc1f395e14377951ac0c9c22ba795.r2.dev/posts/user_38T3Ty5uKeRndW9PUwTFHGYZxwP/8et9aqzo7i------------2026-03-01-------10.36.23.webp) - ㅎㅎ 잘 된다. 속도도 나쁘지 않다.
![스크린샷 2026-03-01 오전 10.39.44|500](https://pub-08bdc1f395e14377951ac0c9c22ba795.r2.dev/posts/user_38T3Ty5uKeRndW9PUwTFHGYZxwP/18mf2vg42wp------------2026-03-01-------10.39.44.webp) #### Antigravity - Antigravity는 아래 그림과 같이 우상단에 점 3개 누르면 나오는 메뉴 중, `Customizations`를 누르면 나오는 화면에서 `Workflows`를 클릭하면 Commands를 설정할 수 있다. - Global/Workspace을 눌러 커맨드가 적용될 환경을 선택하고 커맨드를 만들면 된다. ![스크린샷 2026-02-28 오후 5.58.48|750](https://pub-08bdc1f395e14377951ac0c9c22ba795.r2.dev/posts/user_38T3Ty5uKeRndW9PUwTFHGYZxwP/sr48a0oq4ip------------2026-02-28------5.58.48.webp) - 그러면 아래와 같이 자동으로 `.agents`폴더 아래에 `commands` 명령어를 만들고, 내가 설정한 커맨드 이름의 .md 파일을 생성한 것을 확인할 수 있다. = 즉, 그냥 내가 `agents/commands` 폴더를 만들고 그 아래에 md파일을 생성해서 내가 만들어도 된다는 말!🤗
![스크린샷 2026-02-28 오후 8.37.58|650](https://pub-08bdc1f395e14377951ac0c9c22ba795.r2.dev/posts/user_38T3Ty5uKeRndW9PUwTFHGYZxwP/b739bvd9wmt------------2026-02-28------8.37.58.webp)
## 2. SKILLS 🧰 - Skill은 정말 매력적이다. 앞서 살펴 보앗듯, CLAUDE.md나 AGENTS.md는 작성하면 모든 대화에 항상 토큰을 차지해서 실행되지만 **Skill은 한 번 설정해 놓으면, Agent가 각 상황에 따라 필요하다고 판단되면 알아서 실행한다.** - 이 개념을 `Progressive Disclosure`라고 지칭한다. 맞다. 아까 CLAUDE.md 설명할 때 말한 그 개념이다. Skill은 이 개념을 아래 이미지와 같이 크게 3가지 레벨로 나눠서 구현했다. ![스크린샷 2026-03-03 오후 4.27.02|800](https://pub-08bdc1f395e14377951ac0c9c22ba795.r2.dev/posts/user_38T3Ty5uKeRndW9PUwTFHGYZxwP/bdw9g1e42cq------------2026-03-03------4.27.02.webp) `Level 1. Metadata` - Context에. 즉, 항상 Memory에 반영하는 부분이다. 이 영역을 제외한 나머지를 Memory에 로딩하지 않고 있다가, 사용자의 프롬프트에 맞춰 필요하면 나머지 영역을 읽는다. - Frontmatter는 YAML 파일 형식으로 위 아래 `---` 로 영역을 나눠서 그 사이에 아래 규칙대로 작성한다. - 기본적으로 name, description. 이 2개는 필수다. 사용자가 사용자 의도를 분석해서 description이 매칭되면 자동으로 해당 skill을 로드한다. > [!note] > `name`: > - Maximum 64 characters > - Must contain only lowercase letters, numbers, and hyphens > - Cannot contain XML tags > - Cannot contain reserved words: "anthropic", "claude"
> > `description`: > - Must be non-empty > - Maximum 1024 characters > - Cannot contain XML tags > - Should describe what the Skill does and when to use it > - For complete Skill structure details, see the Skills overview. - 더 많은 옵션은 [여기](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#skill-structure) 참고. `Level 2. Instructions` - Markdown으로 구체적인 명령이 적히는 부분이다. 스킬을 사용하기로 결정되면 로딩된다. `Level 3. Bundled files` - 레벨 2에서 마크다운으로 작성된 내용 중, '이 파일을 참고하세요'와 같이 링크가 걸리면 해당파일을 한 Depth 더 찾아가서 읽게 되면서 레벨 3으로 가게된다. 같은 개념으로 3+ 레벨도 구현이 가능하다. ### SKILL 예시 ✔ - PDF를 처리하기 위한 스킬을 만든다고 했을 때, pdf/ 라는 폴더를 만들고 하위에 아래와 같은 구조로 파일을 생성할 수 있다. ``` pdf/ ├── SKILL.md # Main instructions (loaded when triggered) ├── FORMS.md # Form-filling guide (loaded as needed) ├── reference.md # API reference (loaded as needed) ├── examples.md # Usage examples (loaded as needed) └── scripts/ ├── analyze_form.py # Utility script (executed, not loaded) ├── fill_form.py # Form filling script └── validate.py # Validation script ``` - SKILL.md는 이렇게 생겼고, 아래와 같이 본문에서 /reference.md와 /forms.md를 언급하면서 추가 문서를 참고하게 되는 레벨 3 스킬 예시다. 😎 ![agent-skills-bundling-content|auto](https://pub-08bdc1f395e14377951ac0c9c22ba795.r2.dev/posts/user_38T3Ty5uKeRndW9PUwTFHGYZxwP/nos0e53lbpl-agent-skills-bundling-content.webp)
### 파일 생성 위치 🗂️ - 그렇다면 이 pdf 폴더는 어디에 생성하느냐? commands를 생성한 것과 똑같은데, 폴더 이름만 `skills`로 해주면 된다! 참 쉽죠?👨🏻‍🎨 #### CLAUDE ~/.claude/skills/
    └── my-skill/
               └── SKILL.md
               └── And so on.. project-root/.claude/skills/
    └── my-skill/
               └── SKILL.md
               └── And so on.. #### Antigravity ~/.gemini/antigravity/skills/
    └── my-skill/
               └── SKILL.md
               └── And so on.. project-root/.agent/skills/
    └── my-skill/
               └── SKILL.md
               └── And so on..
## SKILL Store 🏪 - 이렇게 만든 스킬들을 자랑하고 공유하는 시대가 시작됐다. 아래 3개만 대표적으로 소개하지만, 전 세계적으로 너무나 많은 개발자들이 너도나도 좋은 스킬을 만들어서 공유하고 있으니, X나 Threads를 잘 살펴보는 것도 좋겠다.🧐 ### 1. Vercel Skills - 대표적으로 Vercel에서 만든, [skills.sh](https://skills.sh)가 있다. 홈페이지만 들어가봐도, 스킬을 찾는 스킬, react-best-practices, design-guide 등 빨리 설치하고 사용하고 싶은 스킬들이 눈에 띈다.😎 - find-skills 같은 경우는 새로 설치해서 없는 스킬도 찾아 쓸 수 있게 해주는 스킬이다. ㅎㅎ 꼭 설치해놓자. Antigravity, Claude Code 등등 다양한 Agent들을 거의 모두 지원한다. ![스크린샷 2026-03-03 오후 7.22.44|auto](https://pub-08bdc1f395e14377951ac0c9c22ba795.r2.dev/posts/user_38T3Ty5uKeRndW9PUwTFHGYZxwP/84fy53wo8de------------2026-03-03------7.22.44.webp) ### 2. [Anthropic Skills](https://github.com/anthropics/skills?tab=readme-ov-file) - Anthropic 공식 스킬셋 👀. 이라서 Claude Code 전용이다. Creative & Design 스킬 등등 좋아보이는 스킬들이 많다.🤤 ~~일단 설치해부러!!~~ ![스크린샷 2026-03-10 오전 12.25.55](https://pub-08bdc1f395e14377951ac0c9c22ba795.r2.dev/posts/user_38T3Ty5uKeRndW9PUwTFHGYZxwP/hzhpqzwdbsc------------2026-03-10-------12.25.55.webp) ### 3. [Antigravity Awesome Skills](https://github.com/sickn33/antigravity-awesome-skills/tree/main) - Claude Code, Codex, Cursor 등등 다양한 툴 위에서 실행이 가능하다. SKILL도 1234+개🫢 라고 하니, 한 번 구경해보시길! ![스크린샷 2026-03-10 오전 12.23.10](https://pub-08bdc1f395e14377951ac0c9c22ba795.r2.dev/posts/user_38T3Ty5uKeRndW9PUwTFHGYZxwP/tiuqkhjpmn------------2026-03-10-------12.23.10.webp)
## 마무리 🍳 - 모를 때나 무서웠지 정리하고 보니, 다 아래와 같은 생각 때문에 생겨난 도구일 뿐이라는 생각이 든다. > "똑같은 질문에도 더 적은 토큰으로 최고의 효율을 내고 싶다"
> "반복해서 사용할 명령들은 편하게 저장해놓고 편하게 호출하고 싶다."
> "알아서 잘, 딱 깔끔하게, 센스있게 그냥 알아서 해주면 좋겠다."
✨ HAPPY BUILDING! 👷
### References - [CLAUDE API Docs](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) - [Lost in the middle](https://arxiv.org/abs/2307.03172) - [Writing a good CLAUDE.md](https://www.humanlayer.dev/blog/writing-a-good-claude-md) - [Builder.io VISHWAS GOPINATH](https://www.builder.io/blog/claude-md-guide) - [Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?](https://arxiv.org/abs/2602.11988) - [Dheeraj Sharma](https://genaiunplugged.substack.com/p/claude-code-skills-commands-hooks-agents)

Vibe Coding Terms - Part 1

0 comments