본 교재는 생성형 AI 및 Codex Client 환경에서 비정형 대화록 전처리부터 사용자 역할 분류, 기능 요구사항 표 작성, 정상/예외 시나리오 설계, 미결정 질문 구축 및 메일 자동 연동 파이프라인까지의 실무 프로세스를 다룹니다.
이 교재의 목표는 AI에게 “그럴듯한 문서”를 부탁하는 것이 아닙니다. 회의 원문에서 확인된 사실을 추적 가능한 요구사항으로 바꾸고, 개발자가 구현과 테스트에 사용할 수 있는 명세서를 만드는 것이 목표입니다.
단발성 채팅과 Workspace 기반 작업의 차이를 설명한다.
회의록에서 역할, 기능, 규칙, 미결정 사항을 분리한다.
검증 가능한 형식으로 기능 요구사항을 작성한다.
정상 흐름과 주요 예외 흐름을 함께 설계한다.
원문 근거, 누락, 모순, 임의 창작을 점검한다.
산출물을 통합하고 사람이 승인한 뒤 공유한다.
본 교재는 실습 코드 및 프롬프트 문구가 함께 포함되어 있습니다. 상단의 [🖨️ PDF로 저장 / 인쇄] 버튼을 이용하시면 깨끗한 A4 도서 양식의 PDF 파일로 소장하실 수 있습니다.
기존 생성형 AI 사용 환경에서는 매번 대화창에 일회성 프롬프트를 입력하고 단답형 답변을 얻는 방식이 보편적이었습니다. 그러나 실제 비즈니스 SW 개발 및 에이전트 시스템을 구축할 때는 단순히 즉흥적인 질문을 주고받는 것을 넘어, 프로젝트 내 수많은 연관 파일과 규칙을 일관되게 유지하는 '시스템 설계'가 요구됩니다.
| 구분 | ChatGPT 프롬프트 질문 | Codex Workspace 시스템 설계 |
|---|---|---|
| 작업 성격 | 단발성 질의응답 (1회성 대화) | 프로젝트 지속적 감시 및 파일 동기화 |
| 맥락(Context) 유지 | 개인의 프롬프트 작성 능력에 의존 | 다중 파일 간 맥락 자동 캐싱 및 매핑 |
| 결과물 형태 | 텍스트 형태의 단순 답변 | 로컬 폴더 내 정밀 마크다운(MD) 파일 산출 |
| 외부 연동 | 불가 (단순 대화) | 외부 API (Gmail 등) 연동 파이프라인 형성 |
Context(맥락)는 AI가 현재 판단에 사용하는 자료와 규칙의 묶음입니다. 파일이 Workspace에 있다고 해서 모두 정확히 이해되는 것은 아닙니다. 파일명, 최신 버전, 우선순위, 금지 규칙을 명확히 해야 충돌을 줄일 수 있습니다.
AI 에이전트가 단순 대화를 넘어 비즈니스 요구사항을 정밀하게 처리하려면 다음 3단계 파이프라인을 거쳐야 합니다.
프로젝트 내 모든 문서(회의록, 기능 명세서, 비즈니스 룰)가 하나의 규칙 하에 동기화되는 단계입니다.
문서 작성을 넘어 외부 API 및 모듈(예: 이메일 자동 발송)과 실질적인 연동을 수행합니다.
테스팅 및 코드 생성이 용이하도록 정밀 마크다운(`requirements-specification.md`) 문서를 산출합니다.
상황: 팀원이 회의록을 수정했지만 AI는 이전 요구사항을 계속 사용했습니다. 가장 먼저 확인할 것은 무엇일까요?
세 항목을 모두 확인해야 합니다. 특히 “최신 파일을 기준으로 하고, 충돌 시 사용자에게 질문한다”는 규칙을 먼저 적으면 AI가 임의로 버전을 선택하는 위험을 줄일 수 있습니다.
Workspace는 쉽게 말해 AI에게 제공하는 '로컬 기획 공유 폴더'입니다. 사용자가 컴퓨터 바탕화면에 실습 폴더(`automation/`)를 만들고 관련 파일들을 넣어두면, Codex Client는 이 폴더 전체를 두뇌 메모리(Context)로 인지합니다.
• 감시 연동: 폴더 내 meeting-notes.md, open-questions.md 등 모든 문서 감시
• 동시 보완: 한 명세가 변경되면 연계된 모든 문서를 데이터 충돌 없이 동시 업데이트
• 추론 일관성: 원본 문서에 없는 내용을 멋대로 창작하지 않는 Anti-Hallucination 적용
회의 대화록 원문(`meeting-notes-raw.md`)에는 불필요한 사담과 노이즈가 섞여 있어 개발자나 디자이너가 바로 사양서로 쓰기 어렵습니다. 따라서 15줄 이내의 평서문 핵심 요약(`0단계`)을 거친 후, 사용자 역할 및 기능 객체(`1단계`)로 카탈로깅하는 과정이 필수적입니다.
| 구분 | 0단계. 회의록 요약 전처리 | 1단계. 기획 요소 객체 분류 |
|---|---|---|
| 주요 목적 | 핑퐁 대화 및 노이즈 필터링 | 정제된 정보의 성격별 카탈로깅 |
| 수행 동작 | 15줄 이내 평서문 비정형 요약 | 사용자 역할, 기능, 룰, 미결정 사안 분리 |
| 산출 파일 | meeting-notes.md 생성 |
4가지 기획 컴포넌트 객체 정의 |
본 장에서는 비정형 고객 상담 대화록에서 최종 메일 공유 파이프라인까지의 6단계 실습 절차와 각 단계별 전용 프롬프트 및 기대 결과물을 설명합니다.
원본 대화록(`meeting-notes-raw.md`)을 읽고, 인사말이나 사담을 제거한 후 비즈니스 요건 중심으로 15줄 이내의 깔끔한 평서문 회의 메모를 생성합니다.
Input: meeting-notes-raw.md (1시간 상당의 상담 대화록 원문)
Output: meeting-notes.md (15줄 이내 정제된 핵심 기획 요약 메모)
“사용자 편의를 위해 간편 로그인과 추천 기능을 제공한다.” 원문에 없는 기능을 상식이라는 이유로 추가하면 요구사항이 왜곡됩니다.
“고객은 전문가의 가능 시간을 조회하고 상담을 예약한다. 로그인 방식은 회의에서 결정되지 않았다.” 사실과 미결정을 분리합니다.
정제된 `meeting-notes.md`를 바탕으로 서비스의 주요 사용자 역할, 사용자의 수행 기능, 시스템 수행 기능, 비즈니스 규칙, 미결정 사안을 구별합니다.
| 분류 | 예시 | 판단 근거 |
|---|---|---|
| 사용자 역할 | 고객, 전문가, 관리자 | 행동 또는 권한의 주체 |
| 사용자 기능 | 상담 시간 선택 | 사용자가 직접 수행 |
| 시스템 기능 | 예약 완료 알림 발송 | 조건 충족 후 자동 수행 |
| 비즈니스 규칙 | 결제 성공 후 예약 확정 | 업무의 조건과 제약 |
| 미결정 | 취소 수수료 비율 | 승인 또는 추가 협의 필요 |
같은 항목을 두 분류에 중복 배치하지 않고, 모든 항목 옆에 회의록 문장 또는 줄 번호를 근거로 남깁니다. 근거가 없으면 “추정”이 아니라 “미결정”으로 이동합니다.
분류된 객체를 바탕으로 요구사항 명세서의 표 양식에 맞춘 명확한 단문 형태의 문장을 작성합니다.
1. 주어 명시: '[Customer는]', '[시스템은]'과 같이 주어를 분명히 작성한다.
2. 명확한 목적어: 어떤 데이터를 다루는지 대상(예: 전문가 목록, 결제 수단)을 명시한다.
3. 종결어 통일: '~할 수 있어야 한다', '~해야 한다' 스타일로 통일한다.
4. 단문 구성: 한 문장에는 하나의 기능 단위만 포함한다.
“시스템은 빠르고 편리하게 예약을 잘 처리해야 한다.” 빠름, 편리함, 잘 처리함을 측정할 수 없습니다.
“시스템은 결제가 승인되면 예약 상태를 ‘확정’으로 변경하고 고객과 전문가에게 알림을 발송해야 한다.” 조건, 상태 변화, 대상이 보입니다.
[주체]는 [사전 조건]일 때 [입력/대상]에 대해 [행동]을 수행하고 [관찰 가능한 결과]를 제공해야 한다.
문장을 읽은 개발자와 테스터가 같은 화면·데이터 상태를 떠올릴 수 있어야 합니다.
사용자가 서비스를 이용할 때 정상적으로 완료되는 기본 스텝과, 카드 결제 실패나 서버 오류 등 예외 발생 시의 처리 흐름을 설계합니다.
| 흐름 구분 | 정상 흐름 (Happy Path) | 예외 흐름 (Edge Case) |
|---|---|---|
| 상담 예약 시나리오 | 전문가 선택 ➔ 시간 선택 ➔ 결제 성공 ➔ 예약 완료 알림 발송 | 결제 카드 한도 초과/오류 ➔ 실패 안내 모달 ➔ 재결제 시도 유도 |
| 전문가 승인 시나리오 | 서류 제출 ➔ 관리자 검수 ➔ 승인 완료 ➔ 프로필 오픈 | 필수 서류 누락 ➔ 반려 사유 작성 ➔ 전문가 재제출 요청 메일 |
“사용자가 좌석을 예약한다”를 검증 가능한 요구사항 1개와 예외 흐름 2개로 바꾸어 보세요.
요구사항: 이용자는 로그인한 상태에서 예약 가능한 좌석과 이용 시간을 선택하고 결제 요청을 제출할 수 있어야 한다.
예외 1: 다른 이용자가 먼저 결제해 좌석이 점유되면 최신 좌석 목록을 표시한다.
예외 2: 결제 승인이 실패하면 예약을 확정하지 않고 실패 원인과 재시도 방법을 표시한다.
회의 중 명확히 결정되지 않은 수수료 정책, 환불 규칙, 알림 수단 등을 정리하고 고객사/의뢰인 인터뷰 시 바로 사용할 수 있는 질문 리스트 문서(`open-questions.md`)를 작성합니다.
| 좋은 미결정 질문의 구성 | 예시 |
|---|---|
| 결정할 내용 | 예약 당일 취소 시 환불 비율은 얼마인가? |
| 선택지 | A. 환불 없음 / B. 50% / C. 운영자 재량 |
| 영향 | 정산 로직, 약관, 고객 안내 문구에 영향을 줌 |
| 결정권자·기한 | 서비스 책임자 · 개발 착수 전 |
0~4단계에서 작성된 모든 마크다운 문서들을 최종 통합 명세서인 `requirements-specification.md`로 병합하고, Codex Client의 Gmail API 연동을 통해 승인권자에게 자동으로 보고 메일을 전송합니다.
Codex Client 우측 상단의 Gmail 연동 플러그인이 활성화되어 있는지 확인하세요. 메일 발송 전 본문 내 수신자 주소(`to`), 제목(`subject`), 첨부 파일명이 올바른지 최종 검수합니다.
이메일은 먼저 초안으로 생성하고 사람이 수신자, 첨부 파일, 개인정보, 미결정 표시를 확인한 뒤 발송합니다. 실습 중에는 실제 고객 주소 대신 자신의 테스트 주소를 사용하세요.
반려동물 보호자(Pet Owner)와 돌봄 매니저(Pet Sitter)를 연결해 주는 플랫폼 서비스의 요구사항을 정의하는 과제입니다.
• 사용자 역할: 보호자(Customer), 펫시터(Sitter), 운영 관리자(Admin)
• 핵심 기능: 돌봄 일정 조회, 매칭 요청, 사전 예약금 결제, 돌봄 일지 작성
• 미결정 사안: 돌봄 취소 시 당일 환불 비율, 펫시터 신원 보증 보험 가급 여부
키오스크 및 모바일 앱을 통한 스터디룸 좌석 예약 및 문열림 출입 통제 IoT 시스템 요구사항을 정의하는 과제입니다.
• 사용자 역할: 이용자(Student), 매장 점주(Owner)
• 핵심 기능: QR코드 입출입 통제, 좌석 잔여 시간 알림, 스터디룸 조명/에어컨 제어
• 예외 흐름: 퇴실 시간 초과 시 자동 미퇴실 연체료 부과 및 경고 알림
| 검수 항목 | 세부 자가진단 기준 | 점검 결과 |
|---|---|---|
| 1. 역할 정의 | 사용자가 Customer, Expert/Sitter, Admin의 주체로 명확히 나뉘었는가? | [ ] Pass |
| 2. 인과 관계 | 결제 성공 후 예약 확정 및 알림 발송 흐름의 인과가 명백한가? | [ ] Pass |
| 3. 미결정 분리 | 환불/수수료 등 유보 사항이 미결정 사안으로 독립 분리되었는가? | [ ] Pass |
| 4. 사실성 검증 | 대화록 원본에 없는 무관한 기능이 창작되어 포함되지 않았는가? | [ ] Pass |
두 주제 중 하나를 골라 다음 파일을 작성하세요.
meeting-notes.md: 사실 중심 10~15줄open-questions.md: 최소 3문항, 선택지와 영향 포함requirements-specification.md: 기능 요구사항 최소 6개, 예외 흐름 최소 4개아래 메모만을 근거로 요구사항을 작성하세요. 실무에서 중요한 능력은 빈칸을 상상으로 채우는 것이 아니라, 사실과 미결정을 분리하는 것입니다.
역할: 학생, 점주. 출입 장치는 행위 주체인 외부 시스템으로 별도 표기할 수 있습니다.
FR-01 학생은 예약 가능한 좌석을 조회할 수 있어야 한다. FR-02 학생은 좌석을 2시간 단위로 선택할 수 있어야 한다. FR-03 시스템은 결제가 승인된 예약만 확정해야 한다. FR-04 시스템은 유효한 QR 코드가 확인되면 입실을 허용해야 한다. FR-05 점주는 고장 좌석을 예약 불가 상태로 변경할 수 있어야 한다.
정상 흐름: 좌석 조회 → 시간 선택 → 결제 승인 → 예약 확정 → QR 발급 → 입실.
예외: 결제 실패, 선택 중 좌석 선점, QR 검증 실패. 네트워크 장애 처리는 정책이 미정이므로 임의로 정하지 않습니다.
미결정: P1 네트워크 장애 시 출입 정책, P1 결제 수단, P2 취소 수수료. 앞의 두 항목은 핵심 흐름 구현을 막으므로 높은 우선순위입니다.
| 용어 | 쉽게 말하면 |
|---|---|
| Context | AI가 현재 판단할 때 참고하는 파일, 대화, 규칙의 범위 |
| Workspace | 관련 자료와 산출물을 한 프로젝트 단위로 관리하는 작업 공간 |
| Functional Requirement | 사용자나 시스템이 수행해야 하는 관찰 가능한 기능 |
| Business Rule | 기능이 작동하는 조건, 제한, 정책 |
| Happy Path | 오류 없이 목표에 도달하는 대표 정상 흐름 |
| Edge Case | 경계 조건이나 실패 상황에서 필요한 처리 흐름 |
| Open Question | 구현 전에 책임자가 결정해야 하는 미확정 항목 |
| Traceability | 요구사항이 어떤 원문과 결정에서 왔는지 추적하는 성질 |
좋은 AI 활용은 좋은 문장을 빨리 만드는 일이 아니라, 사실과 결정을 추적할 수 있는 구조를 만드는 일입니다.