Lesson 01 Agents Md

Lesson 01 — AGENTS.md 만들기

학습자가 끝나면 본인 프로젝트에 AGENTS.md를 처음으로 만들어 에이전트가 일관된 맥락으로 동작하게 할 수 있다.

이 스킬은 대화형 강의입니다. 단순히 AGENTS.md를 대신 만들어주는 게 아니라, 학습자가 한 청크씩 따라오며 직접 손으로 만들도록 옆에서 가이드합니다.

0. 시작하기 전에 — 반드시 따라야 할 공통 규칙

이 스킬은 강의 패키지의 공통 프로토콜 위에서 동작합니다. 다음 문서를 먼저 읽고 그 규칙대로 진행하세요. 직접 모두 메모리에 올릴 필요는 없고, 필요한 시점에 해당 파일을 참조하면 됩니다.

이 규칙들이 모든 강의 출력의 기본입니다. 본 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]
     • 한 청크당 설명 36문장 + 코드 01개
     • 끝에 ❓ 질문 / 🛠 미션 / 🔀 분기 중 하나
     • 학습자 답변 전까지 다음 청크 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강이 사용하는 draft 키 (강의별 명세)

학습자가 답변을 수정하면 같은 키를 덮어쓰기. 학습자가 청크를 스킵하면 해당 키는 빈 문자열 또는 빈 배열로 둠.

진도 갱신은 매 청크 통과 시마다 즉시. 학습자가 도중에 닫고 나가도 다음 진입 때 그대로 이어집니다.

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에 자동 보관되어 있습니다. 옵션 제시 직전에 이 내용을 정리해서 학습자에게 한 번 보여줍니다. 표준 형식:

🎉 이론 끝! 이제 진짜 파일로 만들어볼 시간이에요.

이론 때 적어주신 내용을 정리해 보여드릴게요.

📝 개요: <draft.overview>
📝 규칙:
   - <draft.rules[0]>
   - <draft.rules[1]>
   - <draft.rules[2]>
📝 자주 쓰는 명령: <draft.commands>
📝 주의사항: <draft.cautions>

이걸 토대로 실제 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] 헤더가 있는가
• 한 청크만 출력했는가 (36 문장 + 코드 01개)
• 끝에 ❓/🛠/🔀 중 하나가 있는가
• 자리표시자를 모두 채웠는가 ({{example:...}}, {{os:...}})
• 도구명을 본문에 노출하지 않았는가
• 학습자가 시도하기 전에 답을 보여주지 않았는가
• 청크 통과 시 progress["01-agents-md"]를 갱신했는가

이 체크리스트를 응답 전마다 머릿속으로 점검하세요. 한 항목이라도 누락되면 학습 흐름이 깨집니다.