AI 하네스 파일 사용법 AGENTS.md와 Codex 지침 구조 이해하기

이 선택 실습은 TaskFlow 작업 관리 앱의 변경 요청을 AI와 함께 검토하는 연습입니다. 요청·코드·검증 결과를 구분해 기록합니다.

이번 주제: AI 하네스 파일 사용법 AGENTS.md와 Codex 지침 구조 이해하기.

TaskFlow 실습

이어서 읽기: AI 바이브 코딩 기준 코드 품질이 무너지기 전 확인할 것. 누적 작업 기록은 docs/ai-log.md에 회차별로 추가합니다. 새로 진입하면 실제 개발환경 시작 ZIP을 별도 폴더에 풉니다. 이 앱에는 상태 문구와 API URL 표시가 있으며 작업 목록·검색·완료 필터는 없습니다. 상단은 지침 파일과 일회성 요청을 분리하는 독립 과제입니다. 하단에서는 실제 스타터가 사용하는 명령을 지침과 작업 로그에 기록하며, 지침 작성 자체를 앱 기능 구현 완료로 기록하지 않습니다.

루트에 프로젝트용 지침 파일을 추가합니다.
포함 내용:
기술 스택 / 실행 명령 / 테스트 명령 / 수정 금지 영역 / 새 의존성 기준 / 비밀정보 규칙 / 완료 전 검증.
너무 긴 문서가 되지 않도록 프로젝트 공통 규칙만 유지합니다.

실습은 가능한 한 작은 변경으로 시작합니다. 변경 전에 현재 working tree를 확인하고, AI가 작업한 뒤에는 대화 내용보다 실제 diff를 기준으로 판단합니다.

git status --short
git diff

프로젝트에 맞는 검증 명령이 있다면 함께 실행합니다.

pnpm lint
pnpm build

이 과정의 TaskFlow 기준은 pnpm 11.19.0이며 lint·build 스크립트를 사용합니다. test 스크립트는 없으므로 npm test나 pnpm test가 통과한다고 기록하지 않습니다. 별도 테스트가 있는 저장소는 package.json의 실제 명령을 추가하고, TaskFlow 동작은 브라우저 확인으로 별도 기록합니다.

변경을 검토하는 방법

Before: 매번 같은 규칙을 프롬프트에 복사
After: 저장소 기본 규칙 + 작업별 요청만 전달

검토할 때는 “코드가 그럴듯한가”가 아니라 요구사항과 diff를 비교합니다.

요청한 파일만 바뀌었는가
기존 규칙을 재사용했는가
새 dependency가 필요한가
오류 처리와 접근성을 놓치지 않았는가
검증 결과가 실제 실행 결과인가
되돌리기 쉬운 변경인가

실패와 위험

• 존재하지 않는 지침 파일명을 표준처럼 설명
• instructions를 권한·보안 정책으로 오해
• 서로 충돌하는 중첩 규칙
• 오래된 명령이나 프로젝트 구조 방치

AI가 틀릴 수 있다는 추상적인 경고보다 실패를 발견할 구조를 만드는 것이 중요합니다. 작은 diff, 명확한 검증 명령, 사람 승인 지점이 있으면 모델이 달라져도 같은 작업 원칙을 유지할 수 있습니다.

완료 체크리스트

• Codex/Claude/Cursor 등 현재 지원 방식 공식 확인
• 실제 TaskFlow 명령과 일치
• 민감정보를 지침 파일에 포함하지 않음
• 다음 회차에서 규칙이 많아질수록 검토량도 늘 수 있음을 연결

누적 기록과 실행 결과

이전 회차 ai-step-03-scope-quality에 남긴 기록을 시작점으로 사용합니다.

현재 구조는 기존 TaskFlow 소스와 package.json을 유지하고, 학습 기록은 새로 만드는 docs/ai-log.md에 누적합니다. 이 경로는 앱 실행 파일이 아닌 실습용 기록 위치입니다. 기존 동명 파일이 있으면 덮어쓰지 않고 회차 항목을 추가합니다. 이번 회차는 저장소 지침 파일도 실제 사용 도구에 맞춰 검토합니다.

Before는 해당 회차의 기록 항목이 없는 상태이고, 적용은 위 실습을 수행하며 관찰 내용을 채우는 과정입니다. After는 아래 항목의 근거와 미검증 범위가 남은 상태입니다. 문서 제목을 바꾸는 것만으로 기능 구현이 완료된 것은 아닙니다.

아래는 docs/ai-log.md에 추가하는 회차 항목 전체입니다. 앱 전체 코드가 아닌 개발 로그 양식이며, 빈칸은 직접 확인한 결과로 채웁니다.

체크포인트: ai-step-04-harness
작업 요청 / 목표 / 비목표:
시작 상태 / 적용 지침:
허용 파일 / 실제 변경 파일:
계획 / diff 요약:
실행 명령 / 실제 결과 / 증거 위치:
미검증 항목 / 필요한 조건:
사람이 확인·수정한 내용:
승인 여부 / 승인 대상:
commit: 미생성 또는 실제 확인한 식별자
실패 지점 / 복구점 / 다음 행동:

검증란은 성공·실패·미실행을 구분합니다. 이 양식 자체는 실행 성공이나 사람 승인 증거가 아닙니다. 앱을 바꿨다면 diff → pnpm lint·pnpm build → 필요한 브라우저 확인 → 사람 검토 → 승인 → commit 순서로 기록합니다. 로그만 편집한 단계는 내용 대조가 검증이며 앱 테스트 통과로 부풀리지 않습니다.

완료 체크포인트

ai-step-04-harness