AI는 코드를 더 많이 작성할 수 있다. 하지만 시스템을 엔지니어링하는 것은 여전히 우리의 몫이다

A drafting compass, loose pieces, an inspection grid and an assembled structure, connected by a line representing an engineering cycle.

사람들이 AI가 소프트웨어 개발을 변화시켰다고 말할 때, 그들이 어떤 부분을 의미하는지 알고 싶습니다. 구현(implementation) 작업일까요? 디자인 탐색일까요? 시스템이 올바른 문제를 해결하는지 결정하는 것일까요?

이러한 활동들은 서로 연결되어 있지만, 하나를 자동화한다고 해서 다른 모든 것이 자동으로 처리되는 것은 아닙니다. 제 주장은 에이전트(agent)가 더 많은 구현 작업을 맡고 분석, 디자인, 테스트를 지원할 수 있지만, 엔지니어는 무엇을 구축할지 결정하고 그것을 받아들이기에 충분한 증거가 무엇인지에 대한 책임은 여전히 지닌다는 것입니다.

이는 업무 방식을 변화시킬 뿐, 책임을 사라지게 하지는 않습니다.

저는 이것을 코드를 쏟아내는 사람을 대체한다고 설명하는 것은 경계합니다. 이는 개발자를 타이핑만 하는 존재로 격하시키고, 에이전트가 지원할 수 있는 범위를 과소평가하며, 작업 자동화를 일자리(jobs)에 대한 주장으로 변질시킵니다. 인력 대체에 관한 주장은 인상적인 시연을 넘어선 증거를 요구합니다.

저에게 더 흥미로운 실질적인 질문은 다음과 같습니다: 우리의 결정을 가시적으로 유지하고 피드백을 유용하게 사용하면서 이러한 도구들을 어떻게 활용할 수 있을까요?

결정에 기록될 장소를 마련하다

대화는 옵션을 탐색하는 데 편리합니다. 하지만 아키텍처적 결정의 유일한 기록을 보관하기에는 매우 취약한 공간입니다.

모델 컨텍스트(Model context)는 한계가 있습니다. 긴 세션은 요약되거나, 압축되거나, 선택된 정보로 재개될 수 있습니다. 요약본은 결론을 보존할 수는 있지만, 그 결론이 합리적이었던 조건을 잃어버릴 수 있습니다. “로컬 캐시를 사용하라”는 것과 “연결성이 없어도 이 화면이 사용 가능해야 하므로 로컬 캐시를 사용하라”는 것은 다릅니다.

Anthropic의 장기간 에이전트에 대한 설명은 컨텍스트 창을 가로지르는 연속성 문제와 증분 작업 및 영구적인 진행 아티팩트(persistent progress artifacts)를 사용하는 접근 방식을 설명합니다. 또한 압축 과정에서 불명확한 지침이 남을 수 있다고 보고합니다. 이것은 보편적인 개발 워크플로우 비교라기보다는 특정 설정을 다룬 벤더 엔지니어링 리포트입니다.

저는 지속 가능한 결정들을 작고 검토 가능한 공간에 두는 것이 가장 좋다고 생각합니다. PROJECT_GUIDE.md 파일에는 다음과 같은 내용이 포함될 수 있습니다:

• 제품의 목적과 현재 범위(명시적 제외 사항 포함).
• 중요한 시스템 경계와 아키텍처 선택의 이유.
• 품질 기대치 및 이를 확인하는 데 사용되는 명령어.
• 더 많은 공간이 필요한 경우, 심층적인 결정으로 연결되는 링크.

파일 이름 자체는 특별한 힘을 갖지 않습니다. 에이전트가 이를 자동으로 로드하지 않을 수 있습니다. 저는 도구에서 지원하는 프로젝트 지침을 통해 연결하거나 작업에 명시적으로 포함시킨 다음, 에이전트의 해석을 확인할 것입니다.

각 증분(increment)마다 관련 파일을 제공하고 의도된 변경 사항, 제약 조건(constraints), 그리고 승인 사례(acceptance cases)에 대한 간략한 설명을 요청할 것입니다. 재진술(paraphrase)은 오해를 포착할 수 있는 초기 기회이며, 구현 단계에서도 준수 여부를 입증해야 합니다.

Simon Willison이 2025년 6월에 논한 컨텍스트 엔지니어링(context engineering)은 다음 모델 단계에 필요한 정보를 선택하는 문제를 이해하는 데 도움이 됩니다. 저의 더 구체적인 권장 사항은 이러한 선택을 의도적으로 수행하고 그 결과를 검토하는 것입니다.

마크다운(Markdown)만으로는 검색(retrieval)이나 복종(obedience)을 보장하지 않습니다. 모든 작업에 모든 문서를 보내면 컨텍스트와 비용이 증가할 수 있습니다. 선택적 검색은 입력을 줄일 수 있지만, 문서를 유지하고, 이를 검색하며, 실수를 수정하는 것 또한 자원을 소모합니다. 절감되었다는 주장은 전체 작업을 측정해야 합니다.

다음 동작 지정하기

가상의 모바일 검색 화면을 고려해 봅시다. 이것은 완료된 프로젝트의 보고서가 아니라 일러스트레이션입니다.

시나리오는 다음과 같을 수 있습니다: “사용자로서, 전체 컬렉션을 스크롤할 필요 없이 저장된 항목을 검색하고 싶습니다.” 첫 번째 증분(increment)의 범위는 기존 항목에 대한 로컬 검색입니다. 원격 검색 및 영속성(persistence) 변경은 제외됩니다.

구현 전에, 저는 이러한 승인 사례를 명시할 것입니다:

일치하는 쿼리는 예상되는 항목들을 표시합니다.
일치하는 결과가 없는 쿼리는 빈 결과 상태를 표시합니다.
쿼리를 지우면 전체 컬렉션이 복원됩니다.
필터링이 비동기적(asynchronous)이라면, 이전 결과가 더 새로운 쿼리의 결과를 덮어쓸 수 없습니다.

이러한 사례들은 기술적인 질문을 제기합니다: 필터링에 비동기 작업이 정말 필요한가요? 에이전트(agent)는 이 결정을 평가하는 데 도움을 줄 수 있습니다. 템플릿이 요구한다고 해서 동시성(concurrency)을 도입하기보다는, 예상되는 데이터 크기와 응답성 요구 사항에 맞춰 해결해야 합니다.

이 예시의 경우, 저는 단방향 데이터 흐름(unidirectional data flow), 명시적인 UI 상태(explicit UI states), 그리고 필터링 로직과 렌더링 간의 분리를 선택할 수 있습니다. 이는 상태 전환을 검사하기 쉽게 만듭니다. 다른 시스템은 다른 구조를 정당화할 수도 있으며, 이것은 목적을 가진 엔지니어링 선택입니다.

프로젝트 가이드는 그 목적을 보존해야 합니다. 기능 수준의 노트는 동작 방식과 모든 새로운 결정을 설명해야 하며, 전체 아키텍처를 재현할 필요는 없습니다.

증분(increment) 후에는 diff를 검사하고, 관련 체크를 실행하며, 화면을 테스트해야 합니다. 만약 에이전트가 범위 제한에도 불구하고 영속성(persistence) 코드를 재작성했다면, 테스트를 통과한다고 해서 그 확장이 허용되는 것은 아닙니다. 빈 상태가 올바르게 보이지만 검색이 잘못된 필드와 일치한다면, 스크린샷 역시 정확성을 입증하지 못합니다.

생성 답변을 검증에 활용하기

에이전트의 출력은 확률적(probabilistic)입니다. 수용 여부는 우리가 검사할 수 있고, 실질적으로 재현할 수 있는 증거에 달려 있어야 합니다.

로컬 검증 명령어(local verification command)는 포맷팅 체크, 정적 분석(static analysis), 컴파일, 그리고 집중 테스트를 실행할 수 있습니다. 이러한 체크들은 서로 다른 질문에 답합니다. 포매터는 규칙(conventions)을 확인하고; 컴파일러는 언어 및 타입 규칙을 확인하며; 테스트는 선택된 조건 하의 선택된 동작을 평가합니다. 어느 것도 우리가 올바른 제품 동작을 선택했음을 확립하지 못합니다.

제어된 검증(Controlled verification) 역시 통제된 입력이 필요합니다. 도구 버전, 픽스처(fixtures), 실행 조건 등이 중요합니다. 타이밍, 장치, 네트워크 또는 외부 서비스를 포함하는 테스트는 불안정할 수 있습니다 (flaky). 테스트 스위트가 결정론적(deterministic)이라고 부른다고 해서 실제로 그렇게 되는 것은 아닙니다.

완벽하게 반복 가능한 검사라 할지라도 잘못된 것을 검증할 수 있습니다. 검색 테스트는 어떤 결과가 나타나는지는 확인하지 않고 단순히 어떤 결과가 나타날 것이라고 단언(assert)할 수 있습니다. 생성된 테스트는 생성된 구현체와 동일한 오해를 충실히 인코딩할 수 있습니다. 저는 승인 사례(acceptance case)에 비추어 검증을 검토하고, 실패 사례를 포함하여 의도적으로 선택된 예시들을 사용해야 합니다.

앱을 실행하는 것은 또 다른 종류의 증거를 추가합니다: 즉, 실제 인터페이스를 통해 동작이 말이 되는지 여부입니다. 성능이 중요할 때는 성공을 선언하기 전에 측정 기준(device, dataset, scenario, threshold)을 정의해야 합니다. 응답성에 대한 빠른 인상은 유용한 피드백이지만, 지연 시간(latency) 결과는 아닙니다.

후크(Hooks)는 로컬 검사를 편리하게 만들고 실수를 더 일찍 포착할 수 있게 합니다. 그 커버리지는 무엇이 이를 트리거하는지, 그리고 우회될 수 있는지에 달려 있습니다. 팀에서 강제 적용을 요구하는 경우, 서버 측 검사 및 리포지토리 보호(repository protections)는 자체적인 구성이 필요합니다. 로컬 후크가 강제된 원격 정책과 동등하지는 않습니다.

엔지니어는 여전히 그 증거가 수용(acceptance), 수정(revision), 또는 거부(rejection)를 뒷받침하는지 결정합니다. 에이전트(agent)는 그 증거를 수집하는 데 도움을 줄 수는 있지만, 불완전한 테스트 스위트를 성공이라고 선언함으로써 완성시킬 수는 없습니다.

문서는 유지보수 가치를 입증해야 한다

작은 변경 사항에도 누군가 작동하는 동작을 보기 전에 긴 체인의 생성된 문서들이 필요할 때 저는 회의적이 됩니다. 각 문서는 검토하고, 조정하며, 최신 상태로 유지해야 하는 무언가가 됩니다. 텍스트를 값싸게 생산한다고 해서 그것을 이해하는 것이 값싼 것은 아닙니다.

이는 비례성(proportionality)과 피드백 주기(feedback cadence)에 대한 비판입니다. 명세 기반 개발(Spec-driven development)은 여러 의미를 가집니다. Birgitta Böckeler가 2025년에 수행한 Kiro, spec-kit, Tessl에 대한 검토는 명세를 먼저 작성하는 접근 방식, 유지보수 중에 이를 보존하는 접근 방식, 또는 이를 주요 출처로 취급하는 접근 방식을 구별합니다. 이러한 차이점들은 비용과 통제를 논할 때 중요합니다.

François Zaninotto가 문서 중심 워크플로우(document-heavy workflows)에 대해 비판한 내용은 보고된 사례들을 통해 검토 오버헤드(review overhead)와 지침 준수에 대한 우려를 제기합니다. 그러한 사례들은 조사에 유용한 단서입니다. 이것들이 명세 자체가 일반적으로 더 나쁜 결과를 초래한다는 것을 입증하는 것은 아닙니다.

점진적인 명세는 빠른 피드백을 지원할 수 있습니다. 애자일(Agile)이 문서를 피한다는 의미는 아닙니다. 그 원칙들은 빈번한 작동 소프트웨어(working software), 기술적 우수성(technical excellence), 그리고 적응성을 강조합니다. 짧은 인수 사례(acceptance case)가 그러한 목표를 달성할 수 있으며, 위험이 정당화될 때는 상세 설계도 마찬가지입니다.

더 강력한 명세는 안전 제약 조건(safety constraints), 규제된 작업(regulated work), 공개 인터페이스(public interfaces), 마이그레이션 호환성(migration compatibility), 그리고 팀 간 조정에 유용할 수 있습니다. 그러한 환경에서, 간결한 가이드라인은 필요한 세부 사항으로 진입하는 지점입니다. 그것이 그 세부 사항을 대체할 수는 없습니다.

제가 문서를 검토하는 실용적인 테스트는 다음과 같습니다: 그것이 어떤 결정, 구현 또는 검증을 지원하며, 누가 이를 유지보수할 것인가? 저는 호환성 제약 조건(compatibility constraint)에 대한 설명이 여러 페이지를 차지하더라도 보존할 것입니다. 결정을 변경하지도 않고 작업 평가에 도움을 주지도 않는 반복적인 산문은 제거할 것입니다.

Matt Pocock의 엔지니어링 기술 모음집은 지침을 적응 가능하고 조합 가능한 조각(composable pieces)으로 패키징하는 또 다른 예시를 제공합니다. 저는 그 방향이 유용하다고 생각합니다. 그것이 명시한 설계 목표가 기술 모음집이 다른 워크플로우보다 우수하다는 증거는 아닙니다.

인수 결정은 명확하게 유지하기 (Keep the acceptance decision explicit)

작은 증분(increment)이라도 여전히 잘못된 가정을 포함할 수 있습니다. 그 장점은 우리가 그것을 발견할 수 있는 더 빠르고 경계가 명확한 기회를 제공한다는 것입니다.

제가 지지하는 루프는 간단합니다: 다음 행동을 정의하고, 필요한 컨텍스트를 공급하며, 해석을 확인하고, 변경 사항을 검사하고, 증거를 수집한 다음, 이를 수용할지 결정합니다. 결정이 바뀌면 지속적인 가이드라인(durable guidance)을 업데이트해야 합니다. 만약 검토 과정 자체가 감당하기 어려워진다면, 에이전트에게 더 많이 생성하도록 요청하기 전에 증가분(increment)을 줄이거나 확인 절차를 개선해야 합니다.

이러한 접근 방식에는 한계가 있습니다. 이는 엔지니어의 이해도, 증거의 품질, 그리고 가이드라인을 최신 상태로 유지하는 비용에 달려있습니다. 본 기사는 통제된 연구나 입증된 생산성 향상이 아닌, 작동 가능한 관점을 제시합니다. 그러한 향상을 확립하려면 단순히 생성 시간만 측정할 것이 아니라, 검토(review), 재작업(rework), 결함(defects), 그리고 유지보수(maintenance)까지 고려하는 비교 가능한 작업이 필요합니다.

저는 요청된 내용, 변경된 내용, 그리고 증거가 이를 수용하는 것을 뒷받침하는 이유를 설명할 수 있을 때 더 많은 작업을 위임하는 것에 편안함을 느낍니다. 이것이 제가 AI 지원 개발에 가져가고 싶은 엔지니어링 표준입니다.

여러분의 워크플로우에서 대화가 끝난 후에도 가시적으로 남아있는 결정은 무엇이며, 어떤 증거가 에이전트가 그 결정을 존중했는지 알려줍니까?

저자 노트: 초기 초안은 Armando Picón의 논거와 출처 검토를 통해 AI 지원으로 생성되었습니다. Armando가 기사를 검토하고 게재를 승인했습니다. 스페인어 번역은 AI 지원으로 제작되었습니다. 모바일 예시는 가상의 것입니다.