AI 코딩 도구 시작 가이드 저장소 컨텍스트 권한 첫 수정 검증

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

작은 문구 또는 단순 UI 수정처럼 영향 범위가 좁은 작업을 선택합니다. 요청 예시 구조: 목표 → 수정 허용 파일 → 수정 금지 영역 → 완료 조건 → 테스트 방법.

TaskFlow 실습

이어서 읽기: VS Code 1.113 업데이트: MCP와 Thinking Effort 변화. 누적 작업 기록은 docs/ai-log.md에 회차별로 추가합니다. 새로 진입하면 실제 개발환경 시작 ZIP을 별도 폴더에 풉니다. 이 앱에는 상태 문구와 API URL 표시가 있으며 작업 목록·검색·완료 필터는 없습니다. 상단의 README 한 문장 수정은 별도 연습 폴더의 작업입니다. 하단에서는 실제 스타터의 상태 문구 수정을 기록하며 두 파일과 결과를 혼동하지 않습니다.

실제 시작 파일은 개발환경 최종 체크포인트의 apps/web/src/main.js입니다. status.textContent에 있던 ‘개발환경 스타터가 실행 중입니다.’를 ‘TaskFlow 개발환경 준비 완료’로 바꾸는 한 곳의 문구 수정으로 연습합니다. 파일을 읽어 시작 문구가 일치할 때만 바꾸고, 다른 앱 상태라면 먼저 요청 범위를 조정합니다. 이는 Next.js의 가상 파일이나 새 기능 구현 결과를 주장하는 예제가 아닙니다.

작은 문구 또는 단순 UI 수정처럼 영향 범위가 좁은 작업을 선택합니다.
요청 예시 구조:
목표 → 수정 허용 파일 → 수정 금지 영역 → 완료 조건 → 테스트 방법.
AI가 수정한 뒤 git diff, lint/test/build 중 해당 검증을 실행하고 사람이 승인한 뒤 저장합니다.

실습은 가능한 한 작은 변경으로 시작합니다. 변경 전에 현재 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: AI에게 “이거 수정해줘”만 전달
적용: 저장소 컨텍스트 + 범위 계약 + diff + 테스트 + 승인
After: 변경 이유와 검증 결과가 로그에 남는 작업
로그 항목: 요청 / 허용 파일 / 변경 파일 / 검증 명령 / 결과 / 승인 여부

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

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

실패와 위험

• 저장소 전체를 무조건 수정 허용
• 비밀정보 노출
• AI 답변만 보고 성공 판정
• 테스트 없이 대규모 수정
• 사용자가 이해하지 못한 명령을 승인
• 기존 변경사항과 AI 변경사항 혼합

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

완료 체크리스트

• 특정 도구 전용 UI를 일반 원리처럼 쓰지 않음
• 현재 공식 문서와 권한 명칭 재확인
• 비밀정보 예시는 실제 값 없이 설명
• TaskFlow 첫 작업이 작은 범위인지 확인
• diff와 검증 결과가 완료 조건에 포함되는지 확인

누적 기록과 실행 결과

처음 진입하는 독자는 위의 독립 연습 폴더부터 시작합니다. 누적 실습은 실행 가능한 TaskFlow와 기존 Git 변경 비교 환경이 준비된 뒤 진행합니다.

현재 구조는 기존 TaskFlow 소스와 package.json을 유지하고, 학습 기록은 새로 만드는 docs/ai-log.md에 누적합니다. 이 경로는 앱 실행 파일이 아닌 실습용 기록 위치입니다. 기존 동명 파일이 있으면 덮어쓰지 않고 회차 항목을 추가합니다. 앱 수정 파일은 저장소 탐색 후 계약에 확정하며 문서의 예시 경로를 실제 파일로 가정하지 않습니다.

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

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

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

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

완료 체크포인트

ai-step-01-start