AI가 생성한 코드를 한 줄이라도 변경하기 전에, 이 7가지를 저장하세요

앱이 작동합니다. AI에게 작은 변경 하나를 요청합니다.

갑자기 레이아웃이 깨지고, 버튼이 응답하지 않으며, 어제 완성했던 기능이 사라집니다.

그래서 오류 메시지를 복사해서 새로운 채팅창에 붙여넣습니다. 모델은 또 다른 수정 방안을 제시합니다. 당신은 그것을 시도해 봅니다.

이제 두 가지 문제가 생겼고 명확하게 되돌아갈 방법이 없습니다.

AI 지원 코딩은 변경 사항을 생성하기 쉽게 만듭니다. 하지만 적용하는 것이 안전하다는 것을 자동으로 만들어주지는 않습니다.

다음 변경을 하기 전에, 5분을 들여 작은 프로젝트 인계(handoff)를 만드세요. 이를 위해 특별한 도구가 필요하지 않습니다. 저장소(repository)의 Markdown 파일로 충분합니다.
**

1. 현재 작동하는 버전 저장하기

다음 변경 사항을 되돌릴 수 있는지 확인하세요.

Git을 사용한다면, 작업 트리(working tree)를 검토하고 의도된 파일만 포함하는 체크포인트 커밋(checkpoint commit)을 만드세요. 비밀 정보(secrets), 생성된 파일 또는 관련 없는 변경 사항을 실수로 포함하지 않도록 주의해야 합니다.

아직 버전 관리를 사용하지 않는다면, 편집하기 전에 프로젝트를 백업하세요. Git은 일찍 배우는 것이 가치가 있습니다.

채팅 기록이 코드 백업은 아닙니다.
2. 정확한 변경 사항 설명하기

“대시보드를 개선해 줘”라는 요청은 해석의 여지를 많이 남깁니다.

이렇게 시도해보세요:

활동 테이블 위에 날짜 필터(date filter)를 추가해 주세요. 기존 레이아웃과 테이블 동작은 변경하지 마세요.

AI에게 목표뿐만 아니라 경계(boundary)도 제시하세요. 범위가 좁게 정의된 작업일수록 검토하고 테스트하기 쉽습니다.
3. 예상되는 동작 작성하기

누군가가 확인할 수 있는 용어로 성공이 무엇인지 설명하세요.

예를 들어:

사용자가 시작일과 종료일을 선택할 때:

• 해당 범위 내의 활동만 표시합니다.
• 양쪽 경계 날짜를 모두 포함합니다.
• 일치하는 항목이 없으면 빈 상태(empty state)를 표시합니다.
• 필터를 지우면 모든 활동으로 복원됩니다.

이는

불확실하다면, 수정하기 전에 AI에게 프로젝트를 검사하여 관련 파일을 식별하도록 요청하세요. AI가 제안하는 범위를 검토하십시오.

자격 증명(credentials), 개인 사용자 데이터 또는 프로덕션 비밀 정보는 공유하지 마세요.

5. 알려진 문제 목록 작성 (List the known issues)

모든 문제가 최신 변경 사항 때문에 발생한 것은 아닙니다.

기존 버그를 기록하여 회귀(regression)인지 이미 고장 나 있던 것인지를 구별할 수 있게 하세요.

알려진 문제:

• 모바일 테이블 오버플로우는 이미 존재함.
• 로딩 상태 개선 필요.
• 내보내기 기능이 구현되지 않음.

이는 또한 모델이 작은 작업을 원치 않는 정리 프로젝트로 확장하는 것을 방지하는 데 도움이 됩니다.

6. 이전에 시도했던 것 기록 (Record what you already tried)

실패한 접근 방식도 유용한 정보입니다.

“우리가 그것을 시도했다”고 말하는 대신, 시도 과정과 결과를 설명하세요:

시도:
페이지네이션(pagination) 이후 필터링(Filtering after pagination).

결과:
현재 페이지에 대해서만 필터링이 이루어져 일부 일치하는 레코드가 누락됨.

결정:
페이지네이션 이전에 필터를 적용할 것.

관찰 사항은 추측과 분리하세요. “이 요청은 500을 반환했습니다”는 증거(evidence)입니다. “데이터베이스가 고장 났음에 틀림없다”는 가설(hypothesis)입니다.

7. 변경되어서는 안 될 것 명시 (Say what must not change)

중요한 결정을 보호하세요:

• 공개 API 동작 방식(Public API behavior)
• 인증 규칙(Authentication rules)
• 데이터베이스 스키마(Database schema)
• 기존 의존성(Existing dependencies)
• 관련 없는 UI 컴포넌트

이것들이 보장 사항은 아닙니다. 여전히 diff를 검사해야 합니다. 하지만 명시적인 제약 조건(constraints)을 제시하면 제안된 수정이 작업 범위를 넘어섰는지 파악하기가 더 쉬워집니다.

복사 가능한 프로젝트 인계 문서 (A copyable project handoff)

이것을 AI_HANDOFF.md로 저장하거나 팀에서 프로젝트 노트를 관리하는 곳에 보관하세요.

현재 작업 (Current task)

작업 체크포인트 (Working checkpoint)

커밋 또는 백업:

요청된 변경 사항 (Requested change)

하나의 특정 결과:

예상 동작 (Expected behavior)

-

관련 파일 (Relevant files)

알려진 문제 (Known issues)

이전 시도 (Previous attempts)

• 시도:
• 관찰된 결과:
• 결정:

제약 조건 (Constraints)

변경되어서는 안 될 것:

검증 (Verification)

실행할 테스트 및 수동 확인 항목:

간결하게 유지하세요. 작업이 변경될 때마다 업데이트하세요.

오래된 인계 문서는 불완전한 프롬프트만큼이나 AI를 오도할 수 있습니다.

지식 기반, 스킬, 에이전트가 도움을 주는 곳

신뢰할 수 있는 프로젝트 정보를 갖추게 되면, 워크스페이스 기능들이 사용하기 더 쉽게 만들어 줄 수 있습니다.

지식 기반(knowledge base)은 요구사항과 의사결정 내용을 접근 가능하게 유지해 줍니다. 스킬(skill)은 회귀 테스트(regressions) 확인이나 누락된 테스트를 점검한 후 스타일 변경을 제안하는 등 반복 가능한 검토 프로세스를 정의할 수 있습니다. 에이전트(agent)는 파일을 검사하고, 변경 사항을 제안하며, 결과를 확인하는 등의 단계를 거쳐 작업을 수행할 수 있습니다.

하지만 이 모든 것이 복구 가능한 코드 체크포인트나 사용자의 diff 검토를 대체하지는 못합니다.

공개 정보: 123sudo의 저희 팀은 9xchat을 구축하고 있습니다. 여기에는 지식 기반, 분리된 메모리 범위(memory scopes), 스킬, 에이전트 워크플로우가 포함되어 있으며, 이는 작업과 모델 전반에 걸쳐 관련 컨텍스트를 유지하는 데 도움을 주도록 설계되었습니다. 위의 핸드오프는 저희의 워크스페이스를 사용하든 다른 것을 사용하든 유용합니다.

변경 사항을 수락하기 전에

diff를 확인하세요. 관련 테스트를 실행하세요. 주요 워크플로우를 연습하세요.

만약 무언가 실패한다면, 추측성 수정(speculative fixes)을 무한정 쌓아 올리기보다는 체크포인트로 돌아가세요.

목표는 완벽한 프롬프트(prompt)를 작성하는 것이 아닙니다. 각 변경 사항을 이해 가능하고, 검토 가능하며, 되돌릴 수 있게 만드는 것입니다.
다음 AI 생성 편집 전에, 핸드오프 템플릿을 복사하여 실제 작업을 하나 수행할 때 채워 넣으세요.

#ai, #programming, #beginners,