새 화면을 만들 때마다 AI 코딩 에이전트가 div와 이벤트 핸들러, DOM 조작 코드, 익숙한 라이브러리를 먼저 꺼내는 문제가 있다면 프롬프트의 표현을 더 정교하게 바꾸기 전에 팀의 구현 규칙부터 점검할 필요가 있습니다.
문제는 에이전트가 최신 API의 이름을 모른다는 데만 있지 않습니다. 기능 요구사항이 “검색어를 강조 표시한다”, “모달을 띄운다”, “입력 영역 높이를 늘린다”처럼 결과만 적혀 있으면, 에이전트는 학습 데이터에 많이 등장한 구현 패턴을 선택하기 쉽습니다. 반대로 팀이 네이티브 기능의 채택 조건, 지원하지 않는 환경의 동작, 접근성 확인 항목을 요구사항으로 주면 코드 생성 결과와 리뷰 기준을 함께 바꿀 수 있습니다.
여기서 목표는 모든 라이브러리를 제거하는 일이 아닙니다. 제품 기능별로 브라우저가 맡아도 되는 책임과 애플리케이션이 계속 맡아야 하는 책임을 나누고, 그 기준을 AI 코딩 에이전트의 기본 구현 규칙으로 만드는 일입니다.
먼저 고를 기능은 “대체 가능성”보다 사용자 영향으로 정한다
네이티브 API 전환 후보는 라이브러리 이름이 아니라 사용자 행동 단위로 목록화하는 편이 낫습니다. 예를 들어 다음처럼 요구사항에 등장하는 기능을 모읍니다.
- 문서나 검색 결과에서 특정 텍스트 구간을 표시한다.
- 팝업, 확인 창, 경고 창처럼 일시적으로 사용자 주의를 모은다.
- 입력 내용에 따라 입력 영역의 크기나 표현을 조정한다.
- 브라우저가 이미 제공하는 입력, 선택, 복사, 상태 표현 기능을 화면별 JavaScript로 다시 만든다.
그다음 각 기능을 세 질문으로 나눠 검토합니다.
-
표현만 필요한가, 문서 구조도 바꿔야 하는가
텍스트 강조는 대표적인 구분 사례입니다. CSS Custom Highlight API는 임의의Range를 만들고 등록한 뒤 CSS::highlight()의사 요소로 스타일을 적용할 수 있습니다. 강조를 위해 텍스트를 여러span으로 감싸지 않아도 된다는 뜻입니다.
다만 강조 대상 자체가 문서의 의미를 바꾸거나, 보조기술에 별도 정보를 전달해야 한다면 시각 효과만으로 요구사항을 충족했다고 볼 수 없습니다. 중요한 정보라면 의미 있는 HTML 요소나 별도 안내가 필요한지 함께 판단해야 합니다. -
브라우저 기능이 제품 규칙을 대신할 수 있는가
네이티브 API는 표시와 상호작용의 일부를 맡을 수 있지만, 권한 확인, 데이터 저장, 감사 기록, 업무 승인 같은 제품 규칙까지 대신하지는 않습니다. 브라우저 기능으로 옮길 영역과 서버 또는 애플리케이션 상태로 남길 영역을 한 요구사항 안에서 분리해 적어야 합니다. -
지원하지 않는 환경에서 기능이 빠져도 되는가
핵심 업무를 완료할 수 없게 된다면 “지원하지 않으면 아무것도 하지 않음”은 폴백이 아닙니다. 반면 보조적인 시각 효과라면 기본 화면을 유지하고 강조만 생략하는 선택도 가능합니다. 이 차이를 기능 중요도와 함께 기록해야 합니다.
전환 우선순위는 코드량이 많은 기능보다, DOM 조작이 복잡하고 화면 변경에 자주 깨지는 기능에서 먼저 잡는 편이 검토하기 쉽습니다. 특히 텍스트를 잘게 감싸거나 풀어내는 코드가 많은 경우에는 네이티브 방식이 DOM 구조를 덜 건드리는지 확인할 가치가 있습니다.
요구사항에 “네이티브 우선”을 쓰는 방식
“가능하면 최신 웹 표준을 사용한다”는 문장은 에이전트와 리뷰어 모두에게 너무 모호합니다. 구현 티켓이나 제품 요구사항에는 선택 규칙을 실행 가능한 문장으로 넣어야 합니다.
다음은 텍스트 강조 기능에 적용할 수 있는 요구사항 예시입니다.
화면은 검색 또는 검사 결과의 텍스트 범위를 강조한다. 브라우저가 CSS Custom Highlight API를 지원하면
Range,Highlight,CSS.highlights를 사용해 DOM 구조를 변경하지 않고 표시한다. 지원하지 않는 환경에서는 강조가 없어도 원문을 읽고 기본 작업을 완료할 수 있어야 한다. 강조가 오류나 주의처럼 의미 있는 상태를 전달한다면 시각적 색상 외의 전달 방법을 별도로 검토한다.
이 문장에는 구현 선택, 감지 대상, 폴백의 최소 기준, 접근성 검토 항목이 함께 들어 있습니다. AI 코딩 에이전트에는 이 문장을 저장소의 개발 가이드, 기능 템플릿, 코드 생성 지시문에 같은 의미로 반영할 수 있습니다.
에이전트에게는 다음과 같은 기본 규칙이 유용합니다.
- 새 의존성을 추가하기 전에 해당 기능을 처리할 네이티브 HTML, CSS, Web API가 있는지 확인한다.
- 네이티브 API를 선택했다면 지원 감지 코드와 폴백 동작을 함께 제출한다.
- DOM을 변형하는 구현을 제안할 때는 네이티브 API로 같은 요구를 충족할 수 없는 이유를 설명한다.
- 접근성에 영향을 주는 표현 기능은 키보드 조작, 포커스, 보조기술 전달 여부를 검토 항목으로 남긴다.
- API 지원 여부를 추측하지 않고, 프로젝트가 정한 대상 브라우저와 실제 동작 검증 결과에 따라 선택한다.
여기서 중요한 점은 “라이브러리 금지”가 아닙니다. 네이티브 API가 요구사항을 충족하지 못하거나, 제품이 지원해야 할 환경에서 필요한 동작을 제공하지 못한다면 기존 구현을 유지하거나 별도 대안을 택할 수 있어야 합니다. 예외를 허용하지 않는 규칙은 결국 에이전트가 억지 구현을 만들게 합니다.
구현 단계에서는 기능 감지와 폴백을 같은 작업으로 묶는다
네이티브 API를 채택하는 작업은 보통 세 개의 산출물로 나눌 수 있습니다.
1. 기능 계약서
기능 책임자와 개발 리드는 사용자에게 보이는 결과를 먼저 적습니다. “강조 표시”라면 누가 어떤 텍스트를 보며, 강조가 사라져도 어떤 업무를 계속할 수 있는지 정합니다. 이 문서는 특정 API 이름보다 사용자 결과를 중심으로 작성합니다.
동시에 아래 항목을 기록합니다.
- 대상 브라우저와 앱 환경
- 기능이 없을 때 허용할 동작
- 강조, 경고, 오류처럼 의미 전달이 필요한 상태인지
- 화면 전환, 데이터 갱신, 텍스트 변경 뒤에도 유지해야 하는 상태인지
- 서버 데이터와 브라우저 표시 상태 중 무엇을 저장해야 하는지
2. 구현 선택 기록
개발자는 후보 API와 기존 방식의 차이를 짧게 남깁니다. 이 기록은 긴 기술 검토 문서일 필요가 없습니다. “DOM 래핑 방식 대신 Range 기반 강조를 우선 검토한다”, “지원 감지 실패 시 원문 표시를 유지한다”처럼 리뷰어가 판단할 수 있는 수준이면 충분합니다.
CSS Custom Highlight API를 사용할 때는 특히 강조 범위가 원문 변경 뒤에도 유효한지 점검해야 합니다. API는 Range를 기반으로 하므로, 화면의 텍스트를 다시 렌더링하거나 교체하는 흐름이 있다면 이전 범위를 언제 제거하고 새로 만들지 구현 규칙으로 정해야 합니다. 등록한 강조를 관리하는 이름 규칙과 정리 시점도 함께 정하지 않으면 화면 상태가 남을 수 있습니다.
3. 검증 시나리오
테스트는 “API가 호출되었는가”가 아니라 “사용자가 같은 업무를 끝낼 수 있는가”를 확인해야 합니다.
최소한 다음 시나리오를 포함할 수 있습니다.
- 지원 환경에서 강조 범위가 의도한 텍스트에만 적용되는가
- 콘텐츠가 바뀐 뒤 이전 강조 표시가 남지 않는가
- 지원하지 않는 환경에서도 원문을 읽고 검색, 검토, 저장 같은 핵심 작업을 할 수 있는가
- 색상이나 배경만으로 중요한 오류 또는 경고를 전달하고 있지 않은가
- 키보드 사용자와 보조기술 사용자가 필요한 정보를 다른 경로로 확인할 수 있는가
CSS Custom Highlight API는 임의의 텍스트 범위를 DOM 구조 변경 없이 꾸밀 수 있지만, 강조 자체가 문서에 의미를 추가하는 것은 아닙니다. 따라서 맞춤 강조를 오류 안내나 검토 지시로 쓴다면, 시각 효과와 의미 전달을 별개로 검증해야 합니다.
운영 규칙은 API 목록이 아니라 예외 기록으로 유지한다
브라우저 기능은 시간이 지나며 지원 범위와 구현 상태가 달라질 수 있습니다. 그래서 “네이티브 API 목록”만 문서에 적어두면 곧 낡습니다. 운영 단계에서는 선택 결과와 예외 이유를 남기는 편이 더 오래 갑니다.
예를 들어 기능별 기록에는 다음만 남겨도 충분합니다.
- 채택한 네이티브 기능 또는 유지한 라이브러리 방식
- 선택 이유
- 지원하지 않는 환경의 동작
- 접근성 확인 결과와 남은 제약
- 재검토가 필요한 조건
이 기록은 AI 코딩 에이전트의 지시문도 함께 갱신하는 근거가 됩니다. 특정 기능에서 네이티브 방식이 적합하지 않았던 이유가 반복된다면, 에이전트에게 “항상 네이티브 API를 사용하라”고 지시하는 대신 “이 조건에서는 기존 방식을 허용하고 이유를 남겨라”라고 규칙을 바꿔야 합니다.
반대로 같은 유형의 DOM 조작 코드가 반복해서 생성된다면, 그 패턴은 프롬프트 문제가 아니라 팀의 기본 구현 기준이 비어 있다는 신호일 수 있습니다.
다음 스프린트에서 정할 것은 API 목록이 아니다
다음 요구사항 검토 때는 “어떤 라이브러리를 제거할까”보다 “우리 제품에서 브라우저가 책임져도 되는 사용자 경험은 무엇인가”를 먼저 정해 보십시오.
텍스트 강조처럼 DOM을 바꾸지 않고도 표현할 수 있는 기능은 좋은 출발점이 될 수 있습니다. 다만 채택 여부는 API의 새로움이 아니라, 대상 환경에서 지원을 확인할 수 있는지, 폴백 뒤에도 업무가 가능한지, 시각적 표현이 전달해야 할 의미를 놓치지 않는지에 따라 결정해야 합니다.
AI 코딩 에이전트가 더 나은 코드를 만들게 하는 기준도 여기에 있습니다. 좋은 지시는 특정 기술 이름을 나열하는 문장이 아니라, 기능 선택과 검증, 예외 처리까지 코드 리뷰에서 같은 답을 낼 수 있게 만드는 팀의 합의입니다.
