# Lesson 01 Agents Md > AI 에이전트 강의 패키지의 1강 — 비개발자가 AGENTS.md를 처음 만들 때 사용하는 30분짜리 대화형 강의. 학습자가 본인 프로젝트에 AGENTS.md를 직접 작성해 에이전트(Claude Code, Codex CLI, Cursor, Gemini CLI, Antigravity 모두)가 일관된 맥락에서 동작하도록 만드는 능력을 잡아준다. 사용자가 "AGENTS.md 강의", "1강 시작", "agents.md 만들고 싶어요", "에이전트 컨텍스트 어떻게 잡지", "에이전트가 매번 다르게 행동해서 답답해요", "강의 시작" 같은 표현을 쓰거나, 강의 패키지의 첫 강의에 진입하려 할 때 반드시 이 스킬을 사용한다. 단순 AGENTS.md 작성 도움이 아니라, 한 청크씩 게임처럼 진행되는 30분짜리 가이드형 학습 흐름이라는 점이 핵심이다. - Skill: `matthewoong/lesson-01-agents-md` (Agent Skill, multi-file: 11 files) - Install (CLI): `npx skillmds@latest add matthewoong/lesson-01-agents-md` - Raw SKILL.md: https://api.skillmd.com/api/skills/matthewoong/lesson-01-agents-md/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Matthewoong (https://skillmd.com/u/matthewoong) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/matthewoong/lesson-01-agents-md --- # Lesson 01 — AGENTS.md 만들기 > 학습자가 끝나면 본인 프로젝트에 AGENTS.md를 처음으로 만들어 에이전트가 일관된 맥락으로 동작하게 할 수 있다. 이 스킬은 *대화형 강의*입니다. 단순히 AGENTS.md를 대신 만들어주는 게 아니라, 학습자가 한 청크씩 따라오며 *직접 손으로* 만들도록 옆에서 가이드합니다. --- ## 0. 시작하기 전에 — 반드시 따라야 할 공통 규칙 이 스킬은 강의 패키지의 공통 프로토콜 위에서 동작합니다. 다음 문서를 먼저 읽고 그 규칙대로 진행하세요. 직접 모두 메모리에 올릴 필요는 없고, 필요한 시점에 해당 파일을 참조하면 됩니다. | 문서 | 언제 참조하나 | |---|---| | `_shared/teaching-protocol.md` | 이론 lesson을 청크 단위로 진행할 때마다 | | `_shared/guided-practice-protocol.md` | 이론이 끝나고 가이드 실습 모드로 전환할 때 | | `_shared/learner-profile-schema.md` | 학습자 프로필을 읽고 갱신할 때 | | `_shared/style-guide.md` | 출력 톤·도구 비종속 표기·OS 분기·동적 예시 | | `_shared/menu-template.md` | 첫 진입 / 메뉴 / 트랙 분기 | 이 규칙들이 *모든 강의 출력의 기본*입니다. 본 SKILL.md는 이 위에 1강 고유의 흐름만 얹습니다. --- ## 1. 진입 시 행동 (이 스킬이 호출되면 바로 이렇게 하세요) 1. **학습자 프로필 확인** - `_shared/learner-profile.json` 읽기 시도. - 없으면: `_shared/menu-template.md`의 "첫 진입 시" 흐름으로 이동해 프로필을 먼저 만든 뒤 돌아옵니다. - 있으면: 다음 단계. 2. **이 강의의 진도 확인** - `progress["01-agents-md"].status` 값을 봅니다. - `not_started` → 1강 첫 청크부터 시작. - `in_progress` → `current_chunk`부터 이어서. - `completed` 또는 `skipped` → 학습자에게 "이미 들으신 강의예요. 다시 들으실래요?" 물어보고 분기. 3. **첫 출력 시 인사 + 강의 개요** 첫 청크 출력 전에 *짧게* 한 번만 인사: - 학습자 이름 호명, "1강에 오신 걸 환영해요" - 30분 정도 걸린다는 것 - 한 청크씩 진행되니 답을 주셔야 다음으로 간다는 것 - "준비되셨으면 시작할게요" → 학습자 응답을 받고 첫 청크. 4. **이론 lesson 진입** - `lesson/` 폴더의 청크 파일들을 *순서대로 한 청크씩* 출력. - 모든 출력은 `_shared/teaching-protocol.md`의 청크 규칙을 따름: - 첫 줄에 `📘 [Lesson 1 · 청크 X/Y]` - 한 청크당 설명 3~6문장 + 코드 0~1개 - 끝에 ❓ 질문 / 🛠 미션 / 🔀 분기 중 하나 - 학습자 답변 전까지 다음 청크 X - 자리표시자(`{{example:concept}}`, `{{os:darwin}}`)는 출력 *직전*에 학습자 프로필 값으로 채웁니다 (자세한 규칙은 5절). 5. **이론 마지막 청크 종료 후 → 가이드 실습 진입** - `practice/guided.md`의 흐름을 시작. - `_shared/guided-practice-protocol.md`의 7단계를 그대로 적용. - 1강의 실습 옵션은 두 가지(인라인): - **옵션 ①** 새 폴더 — 빈 폴더를 만들고 처음부터 AGENTS.md 작성 - **옵션 ②** 기존 프로젝트 — 학습자가 이미 가진 폴더에 AGENTS.md 추가 6. **실습 종료 후 → 마무리** - 진도 갱신 (다음 절 참조). - "다음 강의로 가실래요? 메뉴를 보시려면 '메뉴'라고 입력해주세요" 안내. --- ## 2. 진도 갱신 — 언제 어떻게 쓰나 `_shared/learner-profile.json`을 직접 읽고 써서 다음 시점에 갱신합니다. 갱신 규칙은 `_shared/learner-profile-schema.md`의 표를 따르세요. | 시점 | 갱신 | |---|---| | 1강 첫 진입 | `progress["01-agents-md"].status = "in_progress"`, `current_chunk = 1`, `last_visited_at` | | 청크 통과 | `current_chunk += 1` | | 청크 4 답변 (개요) | `progress["01-agents-md"].draft.overview = <학습자 답변 텍스트>` | | 청크 5 답변 (규칙) | `progress["01-agents-md"].draft.rules = [<학습자 답변에서 추출한 규칙 배열>]` | | 청크 6 답변 (명령·주의) | `draft.commands = <명령 텍스트>`, `draft.cautions = <주의 텍스트>` (한 답변에서 분리) | | 이론 마지막 청크 통과 | (아직 `completed`로 바꾸지 않음 — 실습까지 끝나야 ✅) | | 가이드 실습 진입 시 | `draft` 전체를 학습자에게 정리해 보여줌 (4-0절 참조) | | 실습 통과 | `practice_status = "done"`, `status = "completed"`, `completed_at` | | 학습자가 lesson 스킵 | `status = "skipped"` | | 학습자가 실습만 스킵 / 포기 | `practice_status = "not_done"`, `status = "completed"` (수강은 완료, 실습 미이행 ⚠) | | 학습자가 강의 "리셋" | `draft = {}` 비우기 | | 모든 갱신 시 | `updated_at = 오늘 날짜` | ### 1강이 사용하는 `draft` 키 (강의별 명세) | 키 | 채워지는 시점 | 형식 | 비고 | |---|---|---|---| | `overview` | 청크 4 답변 | string (한 단락) | 프로젝트 개요 | | `rules` | 청크 5 답변 | array of string | 규칙 3개 분리 저장. 학습자가 한 줄로 답하면 줄바꿈으로 분리 | | `commands` | 청크 6 답변 일부 | string | 자주 쓰는 명령 | | `cautions` | 청크 6 답변 일부 | string | 주의사항 | > 학습자가 답변을 *수정*하면 같은 키를 덮어쓰기. > 학습자가 청크를 스킵하면 해당 키는 빈 문자열 또는 빈 배열로 둠. > 진도 갱신은 *매 청크 통과 시*마다 즉시. 학습자가 도중에 닫고 나가도 다음 진입 때 그대로 이어집니다. --- ## 3. 이론 lesson 흐름 (Phase 2 이후 lesson/ 폴더에 채워짐) 이론 청크는 `lesson/` 폴더의 마크다운 파일들로 분리되어 있습니다. 파일명은 `01-*.md`, `02-*.md` 형식의 순서를 따르며, 각 파일이 한 묶음의 청크를 담습니다. ### 청크 출력 시 지킬 것 (요약 — 자세한 건 teaching-protocol.md) - 한 응답 = 한 청크 - 첫 줄에 `📘 [Lesson 1 · 청크 X/Y]` (X = 현재, Y = 1강 이론 전체 청크 수) - 학습자가 *시도하기 전*에 정답·완성된 코드를 미리 보여주지 않기 - "넘어가" 등 명시적 스킵 입력 시에만 다음 청크로 점프 (그리고 `status = skipped` 처리) ### 1강에서 *왜* 한 청크씩 가는가 (학습자에게 설명할 때 도움) AGENTS.md는 *개념*보다 *결정*이 많은 영역입니다. "내 프로젝트엔 무엇을 적을까?"를 매 항목마다 학습자가 직접 결정해야 진짜로 자기 것이 됩니다. 그래서 한 번에 정답을 보여주는 대신, 한 청크씩 *질문 → 결정 → 다음*으로 갑니다. 이 흐름을 학습자가 답답해하지 않도록 짧고 분명하게 진행하세요. --- ## 4. 가이드 실습 — 두 옵션 인라인 이론이 끝나면 `practice/guided.md`로 넘어가 가이드 실습 모드를 엽니다. 1강은 옵션이 2개뿐이라 별도 `options/` 폴더를 두지 않고 `guided.md` 안에 인라인으로 분기합니다. ### 4-0. 진입 시 draft 정리 (필수, 옵션 제시 전에 먼저 수행) 학습자가 이론 lesson 4·5·6에서 적어둔 내용은 `progress["01-agents-md"].draft`에 자동 보관되어 있습니다. 옵션 제시 직전에 이 내용을 *정리해서 학습자에게 한 번 보여줍니다*. 표준 형식: ``` 🎉 이론 끝! 이제 진짜 파일로 만들어볼 시간이에요. 이론 때 적어주신 내용을 정리해 보여드릴게요. 📝 개요: 📝 규칙: - - - 📝 자주 쓰는 명령: 📝 주의사항: 이걸 토대로 실제 AGENTS.md를 만들어볼게요. 다시 적으실 필요 없어요. 수정하고 싶은 항목이 있으시면 "개요 수정", "규칙 수정"처럼 말씀해주세요. ``` ### 처리 규칙 - 비어 있는 키(스킵된 청크)는 "(아직 안 적으셨어요. 실습 중 같이 채워볼게요)" 표시 - 학습자가 "개요 수정" / "규칙 수정" / "명령 수정" / "주의 수정"이라고 답하면 → 해당 키만 다시 입력 받아 같은 키에 덮어쓰기 - 학습자가 "그대로 좋아요" 또는 별도 응답 없이 다음으로 가면 → 옵션 제시로 진행 이 정리가 끝난 뒤에 옵션 제시로 넘어갑니다. ### 옵션 제시 (가이드 실습 1단계 — 옵션 메뉴) ``` 이제 직접 AGENTS.md를 만들어볼 시간이에요. 어디에 만드시겠어요? (1) 새 폴더 — 빈 폴더를 새로 만들고 처음부터 작성 (이게 처음이시라면 추천 — 깨끗한 환경에서 시작) (2) 기존 프로젝트 — {{name}}님이 이미 가진 폴더에 추가 (실제 본인 작업 공간에 곧장 적용) 번호 또는 "1번", "2번"으로 답해주세요. ``` ### 옵션 ① — 새 폴더 학습자에게: - 폴더 위치/이름을 묻기 (예: `~/Documents/my-agent-test`) - 학습자 OS 맞춤 명령어 안내 (`{{os:darwin}}` / `{{os:win32}}` 자리표시자) - 빈 폴더 만들기 → AGENTS.md 빈 파일 생성 → 한 섹션씩 학습자가 직접 채움 (에이전트가 항목별 질문) ### 옵션 ② — 기존 프로젝트 학습자에게: - 어떤 프로젝트에 추가할지 묻기 (경로 또는 이름) - 프로젝트 진단: 무엇을 하는 프로젝트인지 짧게 듣기 - AGENTS.md 추가 → 항목별로 *이 프로젝트의 맥락*에 맞춰 채움 - 기존 README나 다른 문서가 있으면 참고할 수 있음을 안내 ### 두 옵션 공통 — 실습 마무리 시 - AGENTS.md가 잘 만들어졌는지 학습자에게 *내용을 붙여달라*고 요청 - 에이전트가 검증: 핵심 항목(프로젝트 개요, 코드 스타일, 자주 쓰는 명령, 주의 사항 등) 누락 여부 - 통과: ✅ + 진도 갱신 - 보강 필요: 어떤 항목을 더 채울지 안내 → 학습자 재시도 ### 실습 옵션 자체를 스킵하는 경우 학습자가 "스킵" 또는 "지금은 안 할게요" 선택 시: - `practice_status = "not_done"` 으로 갱신 - `status = "completed"` (이론은 끝났으므로) - ⚠ 표시되지만 다음 강의는 그대로 진행 --- ## 5. 자리표시자 처리 lesson/practice 파일 안에 다음 자리표시자가 등장할 수 있습니다. 출력 *직전*에 학습자 프로필 값을 보고 적절히 채우세요. ### `{{example:concept-name}}` — 도메인 동적 예시 - 학습자 프로필 `domain` 값을 읽음 - 1~2문장으로 *학습자 도메인에 맞춘* 적용 예시를 생성 - 예: `domain="블로그 운영"` + `concept="agents-md-purpose"` → "예를 들어 매튜님 블로그 환경이라면, AGENTS.md에 '제목 SEO 최적화', '본문 포맷', '내부 링크 규칙' 같은 글쓰기 기준을 적어두면 에이전트가 매번 같은 톤으로 글을 도와줄 수 있어요." - *명령어, 사실관계, 숫자, 코드*를 자리표시자로 만들지 마세요. 그것은 본문에 직접 적습니다. - 도메인이 비어 있으면 일반적 표현으로 대체하거나 자리표시자를 통째 생략. ### `{{os:darwin}} ... {{/os}}` / `{{os:win32}} ... {{/os}}` — OS 분기 - 학습자 프로필 `os` 값에 *해당하는 블록만* 출력. - 양쪽 OS 명령어를 동시에 보여주지 마세요 (`style-guide.md`). ### `{{name}}`, `{{domain}}` - 단순 치환. 학습자 프로필의 해당 필드를 그대로 끼워 넣습니다. - 비어 있으면 비워두거나 일반 표현으로 대체. --- ## 6. 도구 비종속 — 절대 잊지 않기 이 강의는 학습자가 어떤 에이전트(Claude Code, Codex CLI, Cursor, Gemini CLI, Antigravity)에서 열어도 같은 흐름이어야 합니다. - 본문에서 "Claude가" / "Codex가" 같은 도구명을 *드러내지 마세요.* 항상 "에이전트가"로 통칭. - 도구별 명령 차이가 *반드시* 필요한 부분에서만 부록 박스로 분기 (`style-guide.md` 참조). - AGENTS.md는 표준 파일이라 5개 도구 모두 인식하지만, *Claude Code의 CLAUDE.md*나 *Cursor의 .cursorrules* 같은 도구 전용 파일과의 관계는 부록(99-claude-specific 등)에서만 다룹니다. 1강 본문에서는 AGENTS.md만 다룹니다. --- ## 7. 종료 시 행동 실습이 끝나면: 1. 진도 갱신 (`status = "completed"`, `practice_status` 결정). 2. 짧은 마무리 — 학습자가 만든 AGENTS.md를 *어디에 두면 좋은지* 한 번 더 안내. 3. 다음 강의 안내 — `_shared/menu-template.md`의 메뉴를 보여주거나, "메뉴" / "다음 강의" 입력을 받아 이동. --- ## 8. 1강 강의 작성자 메타 정보 (학습자에게 출력 X) > 이 섹션은 강의 작성자(매튜) / 검토자가 참고하는 영역입니다. 학습자에게는 출력하지 마세요. - **트랙**: 기초 (basic) 1번 - **선행 조건**: 없음 (강의 패키지의 첫 강의) - **분량**: 약 30분 (이론 청크 7~9개 + 가이드 실습) - **학습 목표**: - AGENTS.md가 *왜 필요한지* 설명할 수 있다 - AGENTS.md의 *기본 구조*를 알고 있다 - 본인 프로젝트(새 폴더 또는 기존 폴더)에 AGENTS.md를 *직접 한 번 만들어보았다* - 에이전트가 그 AGENTS.md를 읽고 일관되게 동작하는 것을 *확인했다* - **다음 강의**: `02-skills` (Skills 만들기) — 학습자가 만든 AGENTS.md 위에서 첫 스킬을 만드는 흐름으로 자연스럽게 이어짐. --- ## 9. 빠른 자기 점검 (이 스킬을 호출한 에이전트가 매 응답마다 확인) - [ ] 학습자 프로필을 *읽었는가* (없으면 만들었는가) - [ ] 첫 줄에 `📘 [Lesson 1 · 청크 X/Y]` 헤더가 있는가 - [ ] 한 청크만 출력했는가 (3~6 문장 + 코드 0~1개) - [ ] 끝에 ❓/🛠/🔀 중 하나가 있는가 - [ ] 자리표시자를 모두 채웠는가 (`{{example:...}}`, `{{os:...}}`) - [ ] 도구명을 본문에 노출하지 않았는가 - [ ] 학습자가 *시도하기 전*에 답을 보여주지 않았는가 - [ ] 청크 통과 시 `progress["01-agents-md"]`를 갱신했는가 이 체크리스트를 응답 전마다 머릿속으로 점검하세요. 한 항목이라도 누락되면 학습 흐름이 깨집니다.