에이전트 기반 코딩 실험 2

  • 2025-04-25 (modified: 2025-05-05)

AI 시대의 소프트웨어 공학에 적은 생각을 바탕으로 고쳐본 방식.

기존 실험의 문제점

에이전트 기반 코딩 실험 1에서는 사람이 하던 방식을 에이전트가 최대한 그대로 모방하도록 하려고 했다. 예를 들면 비교적 짧은 보폭의 TDD를 하도록 지시하는 식.

하지만 AI 시대의 소프트웨어 공학에 정리한 작은 깨달음(?)에 의하면 이 방식은 적절치 않아 보인다. 아래와 같은 소프트웨어 공학의 암묵적/명시적 전제들이 상당히 바뀌어야 하기 때문이다.

  • 소프트웨어 개발은 인간이 한다.
  • 인력과 시간은 비싼 자원이다.
  • 인간의 지적 활동에는 여러 특수성이 있다.

하지만 이제 소프트웨어 개발은 AI 에이전트와 인간이 함께 하며, AI 에이전트의 비중이 점차 높아질 것이고, 이에 따라 개발 비용과 소요 시간이 줄어들 것이며, AI 에이전트는 인간과 사뭇 다른 지적(?) 특성을 가진다.

이런 생각을 바탕으로 애자일 방법론에서 조금 벗어난, 전통적인 무거운 방법론(Big M methodologies)을 일부 차용한 프로세스를 생각해봤다.

  • 설계 및 코딩을 기계가 한다면 기존보다는 상대적으로 과하게 선행 설계를 해도 된다. 변경 비용이 낮기 때문이다.
  • 요구사항이 바뀌었을 때 이에 따라 설계 및 코드가 수정되려면 추적가능성(traceability)이 중요하다. AI 에이전트가 추적가능성 관리 및 양방향 엔지니어링(round-trip engineering)을 하기가 용이하도록 지원하는 환경이 필요하다.

기존 실험에서 유지되는 부분

새 LLM 채팅창을 여는 순간, 기존 개발자가 그만두고 새 개발자가 들어온 것과 같다. 따라서 프로젝트의 맥락을 파악할 수 있도록 문서화가 잘 되어 있는 게 중요하다. 다만 기존의 PLAN.md를 발전시키면 좋겠다.

두번째 실험

LLM과 전통적 코드의 협업으로 형식화된 기획서를 관리하기

아래와 같이 형식화된 기획서(BPRD; Business and Product Requirements Document)를 정의한다. 사람이 읽고 수정하기에도 용이하고, 동시에 기계판독성도 높아야 한다.

overview:
  title: 간단한 플래시카드 모바일 웹
  summary: >
  사용자가 어휘 학습이나 다른 주제를 위해 사용자 정의 플래시카드 세트를
  생성, 구성 및 학습할 수 있는 간단한 모바일 웹사이트입니다.
  mission: >
    사용자가 이동 중에도 자신의 플래시카드를 생성하고 복습할 수 있는
  가장 간단한 도구를 제공합니다.
  vision: >
    가장 사용자 친화적인 모바일 플래시카드 도구가 되는 것입니다.
business_objectives:
  - id: BO-001
  description: >
    사용자가 사용자 정의 콘텐츠로 자신만의 플래시카드 세트를 생성하고
    관리할 수 있도록 합니다.
  - id: BO-002
  description: >
    사용자가 카드의 앞면과 뒷면을 보고 넘기면서 플래시카드를 학습할 수 있는
    간단한 인터페이스를 제공합니다.
functional_requirements:
  - id: FR-001
  title: 사용자 회원가입
  covers:
    - BO-003
  prerequisites: []
  description: >
    사용자는 이메일 주소와 비밀번호를 사용하여 새 계정을 만들 수 있습니다.
  - id: FR-002
  title: 사용자 로그인
  covers:
    - BO-003
  prerequisites:
    - FR-001
  description: >
    등록된 사용자는 이메일 주소와 비밀번호를 사용하여 로그인할 수 있습니다.
  - id: FR-003
  title: 사용자 로그아웃
  covers:
    - BO-003
  prerequisites:
    - FR-002
  description: >
    로그인한 사용자는 자신의 계정에서 로그아웃할 수 있습니다.
  - id: FR-004
  title: 플래시카드 세트 생성
  covers:
    - BO-001
  prerequisites:
    - FR-002
  description: >
    사용자는 새로운 빈 플래시카드 세트를 만들고 이름을 지정할 수 있습니다.
  - id: FR-005
  title: 플래시카드 추가
  covers:
    - BO-001
  prerequisites:
    - FR-004
    - FR-002
  description: >
    사용자는 기존 세트에 새 플래시카드를 추가하고 카드의 앞면과 뒷면에
    대한 텍스트를 제공할 수 있습니다.
  - id: FR-006
  title: 세트 및 카드 관리
  covers:
    - BO-001
  prerequisites:
    - FR-004
    - FR-005
    - FR-002
  description: >
    사용자는 자신이 만든 세트 목록을 볼 수 있습니다. 세트를 선택하면 해당
    세트 내의 카드 목록을 볼 수 있으며, 개별 카드나 전체 세트를 편집하거나
    삭제할 수 있는 옵션이 있습니다.
  - id: FR-007
  title: 플래시카드 학습 모드 (뒤집기)
  covers:
    - BO-002
  prerequisites:
    - FR-006
    - FR-002
  description: >
    사용자는 세트를 선택하고 카드가 하나씩 표시되는 학습 모드로 들어갈
    수 있습니다. 카드를 탭하면 뒷면이 나타나고, 사용자는 세트의 카드를
    탐색할 수 있습니다.
acceptance_tests:
  - id: AT-001
  covers: FR-001
  description: >
    사용자가 회원가입 페이지에 있을 때, 유효한 이메일 "test@example.com"과
    비밀번호 "password123"을 입력하고 "회원가입"을 탭하면, 로그인되어 메인
    페이지로 리디렉션됩니다.
  - id: AT-003
  covers: FR-003
  description: >
    사용자가 로그인되어 있을 때, "로그아웃" 버튼을 탭하면, 로그아웃되고
    메인 페이지로 리디렉션됩니다.
  - id: AT-004
  covers: FR-004
  description: >
    사용자가 메인 페이지에 있을 때, "새 세트 만들기"를 탭하고 이름
    "내 단어장"을 입력하면, "내 단어장"이라는 이름의 세트가 세트 목록에
    나타납니다.
  - id: AT-005
  covers: FR-005
  description: >
    '사용자가 "내 단어장" 세트를 만들고 보고 있을 때, "카드 추가"를
    탭하고 "단어: Hello", "정의: 안녕하세요"를 입력하면, "Hello/안녕하세요"
    카드가 "내 단어장" 세트에 추가됩니다.'
  - id: AT-006
  covers: FR-006
  description: >
    사용자가 메인 페이지에 있을 때, 세트 목록에서 "내 단어장"을 보고
    탭하면, "Hello/안녕하세요"를 포함하여 "내 단어장"의 카드를 보여주는
    페이지로 이동합니다.
  - id: AT-007
  covers: FR-006
  description: >
    '사용자가 "내 단어장"의 카드를 보고 있고 "Hello/안녕하세요"를 편집하기
    위해 탭했을 때, "정의: 안녕하세요"를 "정의: 안녕"으로 변경하면, 카드가
    "Hello/안녕"으로 업데이트됩니다.'
  - id: AT-008
  covers: FR-006
  description: >
    사용자가 "내 단어장"의 카드를 보고 있고 "Hello/안녕하세요"를 삭제하기
    위해 탭했을 때, 삭제를 확인하면 "Hello/안녕하세요" 카드가 "내 단어장"
    세트에서 제거됩니다.
  - id: AT-009
  covers: FR-007
  description: >
    사용자가 "내 단어장"의 카드를 보고 있을 때, "학습" 버튼을 탭하면,
    첫 번째 카드의 앞면("Hello")이 표시됩니다.
  - id: AT-010
  covers: FR-007
  description: >
    사용자가 카드의 앞면("Hello")을 보고 있을 때, 카드를 탭하면, 카드의
    뒷면("안녕하세요")이 표시됩니다.
  - id: AT-011
  covers: FR-007
  description: >
    사용자가 카드의 뒷면("안녕하세요")을 보고 있을 때, 카드를 다시 탭하면,
    카드의 앞면("Hello")이 다시 표시됩니다.
  - id: AT-012
  covers: FR-007
  description: >
    사용자가 카드를 보고 있을 때, 다음 카드로 이동하면(예: 스와이프 또는
    버튼), 세트의 다음 카드 앞면이 표시됩니다.

기획서에서 (전통적인 의미에서) 기계가 이해할 수 있는 부분을 검사해주는 CLI 프로그램을 만든다. 이 프로그램은 비즈니스 목표(BO)에서 출발해서 기능 요구사항(FR)을 거쳐 인수 테스트(AT)로 이어지는 그래프에 논리적인 문제가 없는지 검사해준다.

예를 들어 이런 식:

$ deva check < BPRD.yaml
UNKNOWN_BO_ID: FR-001 references BO-003.
UNKNOWN_BO_ID: FR-002 references BO-003.
UNKNOWN_BO_ID: FR-003 references BO-003.
UNCOVERED_FR: FR-002 is not covered by any acceptance test.

Cursor의 Rule 파일에 BPRD 문서의 양식 및 deva라는 툴 사용법을 등록하면 에이전트가 결함 없는 요구사항 문서를 잘 만들어주고 적절히 수정도 해준다. 예를 들어 “이런저런 기능을 추가해줘”라고 시키면 기능 요구사항 및 관련 인수 테스트를 추가하고 CLI 프로그램을 알아서 실행하여 모든 문제가 잡힐 때까지 적절히 수정한다. LLM이 텍스트를 이해하고 CLI가 논리적 결함을 검사해주는 식으로 두 시스템이 서로의 단점을 보완해주는 방식(일종의 neuro-symbolic system)이다.

형식화된 기획서를 바탕으로 맥락을 유지하며 코딩하기

BPRD.yaml 문서 및 적절한 Rule 파일이 있는 상태에서 “FR-001을 구현해”라고 시키면 알아서 구현을 하고 필요한 인수 테스트를 작성해준다. 특정 명령(예: npm run check-all)을 실행하면 linter, formatter, type checker, unit testing, acceptance testing을 모두 실행하고 결과를 알려주기 때문에 에이전트가 모든 문제가 다 해결될 때까지 혼자 일한다. (대체로 성공하는데 간혹 실패한다)

이를테면 이런 Rule 파일들을 등록해준다:

---
description:
globs: e2e/**/*.test.ts
alwaysApply: false
---

Acceptance tests should be in `e2e` directory and named according to [BPRD.yaml](mdc:BPRD.yaml), e.g.: `AT-001.test.ts`

Whenever you add, modify, or remove acceptance tests, always run `npm run deva` and fix any problems it reports.

---
description:
globs:
alwaysApply: true
---
This project uses DEVA - The Software Development Agent.

## BPRD

[BPRD.yaml](mdc:BPRD.yaml) contains Business and Product Requirements Document (BPRD). This document is the single source of truth for the entire project. It provides traceability between the business objectives (`BO-nnn`), functional requirements (`FR-nnn`), acceptance tests (`AT-nnn`), and actual implementations. Whatever you do, always read this document first.

Whenever you modified `BPRD.yaml`, always run `npm run bprd`. Fix any problems it reports.

## Getting feedback

Whenever you modified code, always run `npm run deva` to run all the checks and tests. Fix any problems it reports.

남은 할 일

이런 걸 더 해보면 좋을 것 같다.

  • 어떤 기능요구사항이 구현되었는지 여부를 트래킹하기. 소스코드에 특별한 형태의 주석을 남기는 등의 방법으로 비즈니스 목표(BO), 기능요구사항(FR), 인수테스트(AT), 실제 구현이 연결되는지 여부를 분석하고 에이전트에게 알려주는 CLI 도구 추가
  • BPRD 문서를 기반으로 기계판독가능한 설계 문서를 정의하기. BPRD-설계문서-코드 사이의 정합성을 분석해주는 CLI 도구 추가
  • 에이전트가 단위 테스트를 작성하고 테스트 커버리지 측정하여 일정 기준을 만족하도록 하기. 어차피 사람이 작업할 게 아니므로 분기 커버리지 이상의 기준으로 측정해보는 실험도 해보기
  • 인지복잡도 등 복잡도 측정하기. (AI가 코딩을 하더라도 복잡도 관리는 여전히 중요하다. 자세한 내용은 AI 시대의 소프트웨어 공학 중 “코드 품질” 부분 참고)

2025 © ak