AI 코딩 에이전트에게 긴 지시문 대신 남겨야 할 것: 작은 프로젝트 규칙

핵심 요약 (TL;DR)

AI 코딩 에이전트에게 일을 맡길수록 지시문은 길어지기 쉽습니다. 최근 HN에 소개된 오픈소스 프로젝트 Knowl도 ‘AI 에이전트용 지식 운영’이라는 문제를 전면에 둡니다. 이 프로젝트가 모든 팀의 해답이라는 뜻은 아닙니다. 오히려 초보 바이브코더에게 남는 질문은 단순합니다. 매번 같은 설명을 다시 쓰기 전에, 내 서비스에서 바뀌면 안 되는 판단을 짧게 남겨 두고 있는가입니다.

왜 긴 프롬프트가 프로젝트를 더 안전하게 만들지 않을까요?

긴 지시에는 목표, 예외, 과거의 시행착오, 순간적인 취향이 한꺼번에 섞이기 쉽습니다. 그러면 다음 작업에서 무엇이 규칙이고 무엇이 일회성 요청인지 구분하기 어려워집니다. 에이전트가 잘못 이해했을 때도 어디를 고쳐야 하는지 모호해집니다.

대신 규칙을 세 층으로 나눠 보세요. 첫째는 제품의 약속입니다. 예를 들어 ‘사용자 입력은 저장 전에 다시 확인한다’처럼 서비스가 지켜야 할 일입니다. 둘째는 화면의 기준입니다. ‘새 화면에는 로딩·빈 상태·오류 상태를 함께 둔다’처럼 확인 가능한 문장입니다. 셋째는 작업 방식입니다. ‘수정 전에는 바뀌는 파일과 확인 방법을 먼저 알린다’처럼 협업의 경계입니다.

작은 프로젝트 규칙은 어떻게 쓰면 될까요?

프로젝트 첫 화면에 짧은 문서 하나를 두고 열 줄 안팎으로 시작하세요. 비밀값을 코드에 넣지 않는다. 개인정보는 테스트 데이터로 확인한다. 기존 컴포넌트를 찾은 뒤 새로 만든다. 모바일 폭에서 확인한다. 기능을 바꾸면 테스트 방법을 함께 적는다. 이런 문장은 도구가 달라져도 남습니다.

규칙은 언제 늘려야 할까요?

실제로 같은 실수가 두 번 반복됐을 때입니다. 처음부터 백 가지 규칙을 쌓으면 아무도 읽지 않습니다. 반대로 오류를 고친 뒤 ‘다음에는 무엇을 확인하면 막을 수 있나’를 한 줄로 남기면 문서는 살아 있는 안전장치가 됩니다.

에이전트에게는 무엇을 요청해야 할까요?

작업을 시작할 때 ‘이 프로젝트 규칙을 읽고, 이번 변경에서 지켜지지 않는 항목이 있으면 먼저 알려 주세요’라고 요청하면 충분합니다. 이어서 수정 범위, 변경 파일, 화면에서 확인할 방법을 받으세요. AI에게 정답을 위임하는 대신, 판단 과정을 눈에 보이게 만드는 방식입니다.

FAQ: 문서를 잘 쓰려면 개발 지식이 많아야 하나요?

아닙니다. 내가 반복해서 불편했던 장면을 평범한 문장으로 적으면 됩니다. 예를 들어 ‘버튼을 누르면 아무 반응이 없어 불안했다’는 경험은 오류·로딩 상태 규칙의 좋은 출발점입니다.

FAQ: 도구별 규칙을 따로 만들어야 하나요?

제품 규칙은 공통으로 두고, 실행 명령이나 파일 구조처럼 도구에 따라 달라지는 내용만 짧게 분리하면 됩니다. 핵심은 특정 도구에 묶이는 것이 아니라 사용자의 약속을 보존하는 것입니다.

출처
- Knowl GitHub 원문: https://github.com/dat999zx/knowl
- HN 소개: https://news.ycombinator.com/item?id=49399703
- 관찰 시점: 2026-08-23 KST. Knowl은 초기 오픈소스 프로젝트이며 본문의 프로젝트 규칙 제안은 해당 사례에서 확장한 실무적 해석입니다.