에이전트 개발 기획서

1.1개발할 제품을 한 문장으로 고정한다

1.2자동화의 범위와 사람의 역할

1.3기능 요구사항과 인수 기준

1.4성공을 어떤 숫자로 판단할 것인가?

초기 목표는 보장된 성능이 아니다. 실제 자료·모델·외부 연동으로 측정한 결과를 인수 문서에 기록한다.

2.1모델은 판단하고, 실행 시스템은 권한과 상태를 관리한다

2.2채택 구조와 대안의 판단 근거

2.3저장할 데이터와 불변 조건

2.4외부 시스템이 제공해야 할 계약

3.1읽기 판단 루프와 쓰기 경로를 분리한다

3.24개 읽기 도구와 별도 쓰기 계약

3.3구조화된 결과 계약

{
  "schema_version": "1",
  "outcome": "ANSWER_WITH_PROPOSAL",
  "answer": "QA 기록에서 모바일 첨부 업로드 검수 결과를 찾지 못했습니다.",
  "claims": [
    {
      "text": "모바일 첨부 업로드 검수 근거가 확인되지 않음",
      "evidence_ids": [
        "ev_spec_14",
        "ev_qa_08"
      ]
    }
  ],
  "uncertainties": [
    "검색 범위 밖 자료에 검수 기록이 있을 수 있음"
  ],
  "proposal": {
    "title": "모바일 첨부 업로드 검수",
    "body": "요구사항 UP-04에 대한 390px 화면의 업로드·오류 안내 검수",
    "project_id": "project_aurora",
    "assignee_id": null,
    "due_at": null
  }
}

가상 응답 예시. “검수 근거가 없다”와 “검수를 하지 않았다”를 구분한다. outcome은 ANSWER / ANSWER_WITH_PROPOSAL / NEEDS_INPUT / INSUFFICIENT_EVIDENCE 중 하나다.

3.4세 가지 상태를 따로 표시한다

4.1SCR-01 · 요청, 진행, 근거 답변

4.2SCR-02 · 실행할 내용 자체를 검토한다

4.3SCR-03 · 실행 이력과 운영 조사

4.4화면 공통 규칙

4.5HTTP API 계약 · /api/v1

{
  "revision": 2,
  "payload_hash": "sha256:…",
  "decision": "APPROVED",
  "reason": "근거와 담당자·기한을 확인함"
}

{
  "error": {
    "code": "PROPOSAL_REVISION_CONFLICT",
    "message": "등록안이 변경되었습니다.",
    "retryable": false
  },
  "trace_id": "trace_1042"
}

5.1책임이 분리된 모듈 구조

5.2서버에서 강제할 두 개의 트랜잭션

async function publish(executionId) {
  const action = await claimExecution(executionId);
  await recheckAccessAndApproval(action);
  // 저장된 승인 payload만 사용. 모델 재호출 없음.
  try {
    const receipt = await taskAdapter.create({
      payload: action.approvedPayload,
      idempotencyKey: action.actionKey
    });
    await markApplied(action, receipt);
  } catch (error) {
    // 전송 여부를 확정할 수 없으면 실패로 단정하지 않음.
    await recordFailureOrUnknown(action, error);
  }
}

설계 의사 코드. 실제 구현은 claim lease·fencing, 외부 오류 분류, 만료·권한 재검사, UNKNOWN 조회 복구를 포함해야 한다.

5.3단계별 개발 티켓

5.4AI 개발자에게 전달할 작업 카드

작업 ID: DEV-07
목표: 승인 대상과 실제 등록 payload가 항상 일치한다.
변경 범위: ProposalService, API-08~10, SCR-02
입력: proposal_id, base_revision, payload, actor context
규칙: 수정은 새 revision / 승인 승계 금지 / tenant 서버 주입
실패: 409 버전 충돌 / 403 역할 부족 / 422 입력 오류
금지: 모델에게 승인 권한 부여, 승인 payload 덮어쓰기
검증: TC-05, TC-06 / 경합 결과와 DB 행 수 첨부
제출: 변경 코드, migration 여부, API 예시, 검수 증거, 남은 제약

5.5인수할 파일 묶음

6.1요구사항에 연결된 12개 인수 시나리오

6.2평가를 세 층으로 나눈다

6.3실제로 제출할 QA 결과 형식

6.4운영 기준과 비용 산정

6.5장애 발생 시 행동과 출시 판단

6.6착수 전에 담당자가 확정할 결정