대부분의 에이전트 데모는 코딩 어시스턴트가 작은 저장소(repo)를 편집하는 모습을 보여줍니다. 하지만 QA/API 자동화 작업은 보통 훨씬 더 복잡합니다.

실제 API 테스트 변경을 위해서는 에이전트가 다음 사항들을 이해해야 할 수도 있습니다:

• 엔드포인트(endpoint) 및 OpenAPI 계약(contract),
• 기존 API 테스트 프레임워크(framework),
• 공유된 요청/단언(assertion) 유틸리티,
• 서비스 동작,
• 테스트 데이터 또는 픽스처(fixtures),
• 그리고 실패한 기대값이 실제로 제품의 결함(product gap)인지 여부.

이 저장소(repo)는 해당 문제에 대한 실용적인 패턴을 탐구합니다:

작은 작업 컨텍스트(small task context) + 생성된 저장소 컨텍스트(generated repo context) + 재사용 가능한 QA 플레이북(reusable QA playbooks) + 검증(verification)

현재 구현은 8GB MacBook Air에서 로컬 에이전트(local agents)를 사용하지만, 이 프레임워크가 로컬 에이전트에 국한된 것은 아닙니다. 핵심 아이디어는 모델 호스팅(model hosting)이 아니라 컨텍스트 라우팅(context routing)이기 때문에, 클라우드 코딩 에이전트와도 동일한 구조를 사용할 수 있습니다.

저장소(Repo):

https://github.com/balajiregt/agentic-workspace

QA 문제
API 자동화 에이전트는 종종 예측 가능한 방식으로 실패합니다:

• 엔드포인트에 이미 커버리지(coverage)가 있음에도 새로운 테스트 파일을 생성함,
• 엔드포인트 경로, 기본 URL(base URLs), 또는 요청 본문(request bodies)을 임의로 만들어냄,
• 공유된 API 테스트 유틸리티를 무시함,
• OpenAPI를 확인하지 않고 테스트를 업데이트함,
• 단순히 테스트 스위트(suite)를 통과(green)시키기 위해 실패하는 테스트를 삭제하거나 다시 작성함.

QA 관점에서 마지막 케이스는 특히 위험합니다. 만약 테스트가 서비스에서 구현되지 않았고 OpenAPI에도 문서화되지 않은 동작을 기대하고 있다면, 에이전트는 이를 제품/계약의 결함(product/contract gap)으로 지적해야 합니다. 결함을 숨겨서는 안 됩니다.

워크스페이스 형태(Workspace Shape)
샘플 검증 슬라이스는 Spring Boot와 RestAssured를 사용하지만, 이 패턴은 API 프레임워크에 중립적입니다.

agentic-workspace/ AGENTS.md # 리포지토리 수준의 에이전트 규칙 (repo-level agent rules) contexts/current/ # 현재 티켓 컨텍스트 (current ticket context) skills/ # 압축된 QA/API 에이전트 플레이북 (compact QA/API agent playbooks) scripts/ # 컨텍스트 해결사 및 토큰 보고서 (context resolver and token reports) local-agents/ # 선택 사항인 로컬 Pi + llama.cpp 런타임 (optional local Pi + llama.cpp runtime) projects/ microservices/ xyz-service/ # 더미 Spring Boot API (dummy Spring Boot API) xyz-deployments/ # 배포 컴패니언 파일 (deployment companion files) qa-steps/ # 공유 API 테스트 유틸리티 (shared API-test utilities) qa-projects/xyz-service-api-tests/ # 서비스 API 테스트 (service API tests)

더미 서비스는 의도적으로 작게 구성되었습니다. 핵심 가치는 실제 QA 자동화 변경 사항이 가로지르는 것과 동일한 경계들, 즉 서비스 동작(service behavior), 계약(contract), 공유 테스트 유틸리티(shared test utilities), 서비스별 API 테스트(service-specific API tests), 그리고 검증(verification)을 모두 아우른다는 점에 있습니다.

에이전트 흐름 (Agent Flow)

에이전트는 작은 티켓 컨텍스트(ticket context)에서 시작하여, 필요한 경우에만 정확한 파일들로 확장해 나갑니다.

컨텍스트 분할 (The Context Split)
이전에는 YAML 파일에 너무 많은 정보(정확한 경로, 대상 파일, 명령어, 예시, 동작 힌트 등)를 넣으려고 시도했습니다. 이는 프레임워크를 유지 관리하기 더 어렵게 만들었습니다.

더 깔끔한 분할 방식은 다음과 같습니다:

service-context.yml -> 작은 티켓 사실 관계 (small ticket facts) OpenAPI + 리포지토리 레이아웃 -> 안정적인 서비스 사실 관계 (stable service facts) resolved-context.yml -> 생성된 정확한 경로 및 명령어 (generated exact paths and commands) SKILL.md -> 재사용 가능한 QA/API 플레이북 규칙 (reusable QA/API playbook rules)

현재 작업 컨텍스트는 작게 유지됩니다:

Then resolver는 다음과 같은 경로들을 생성합니다:

resolved_files.openapi resolved_files.service resolved_files.api_test resolved_files.shared_fixtures resolved_files.shared_assertions verification.commands

이는 사용자가 다음과 같이 짧은 프롬프트를 제공했을 때 도움이 됩니다:

기존 API 테스트에 riskCategory가 비어있지 않다는 단언(assertion)을 추가해 주세요.

사용자가

올바른 QA 답변은 다음과 같습니다:

이것은 제품/계약 간의 격차(gap)입니다. 서비스 검증을 추가하고 OpenAPI를 업데이트하거나, 이유를 명시하여 테스트를 보류(pending) 상태로 표시하십시오.

이는 단순히 테스트를 통과시키는 것과는 다릅니다. 에이전트는 QA 시그널(signal)을 보존해야 합니다.

로컬 에이전트 검증 (Local Agent Validation)
이 방식이 평범한 사양의 머신에서도 작동할 수 있음을 증명하기 위해 로컬 런타임(runtime)이 포함되었습니다:

npm run setup:8gb npm run agent:8gb

검증된 로컬 모델:

unsloth/gemma-4-E2B-it-qat-GGUF:UD-Q4_K_XL contextWindow: 4096 maxTokens: 1536

수정 사항을 신뢰하기 전에 다음을 실행하십시오:

npm run agent:doctor

예상 결과:

TOOL_CALL_CHECK=PASS

이것이 중요한 이유는 일부 GGUF 모델들이 구조화된 도구 호출(tool calls)을 반환하는 대신, 도구 형태의 JSON을 텍스트로 출력하기 때문입니다. 그러한 모델들은 분석에는 유용할 수 있지만, 신뢰할 수 있는 파일 수정에는 적합하지 않을 수 있습니다.

토큰 효율성 증명 (Token Efficiency Proof)
현재 집중된 API 테스트 변경 보고서:

Central context tokens: 174 Central context plus playbook tokens: 2386 Full microservices corpus tokens: 5309 Task profile tokens: 4810 Central context compression ratio: 30.51x

저는 이 수치들을 공식적인 벤치마크 숫자가 아닌, 대략적인 로컬 측정값으로 취급합니다. 토큰 추정기(token estimator)는 한 워크스페이스 버전을 다른 버전과 비교하기 위한 간단한 척도입니다. 이는 방향성을 제시하는 데 유용합니다. 즉, 유지되는 티켓 컨텍스트(ticket context)는 작으며, 에이전트는 필요할 때만 작업 파일로 확장된다는 점입니다. 정확한 수치는 토크나이저(tokenizer), 모델, 리포지토리(repo) 크기, 파일 형식, 그리고 에이전트 런타임이 도구/컨텍스트 메시지를 패킹(packing)하는 방식에 따라 달라질 것입니다.

토큰은 유용한 시그널을 보존하면서도 가능한 한 낮게 유지되어야 합니다. 목표는 어떤 대가를 치르더라도 컨텍스트를 아주 작게 만드는 것이 아닙니다. 목표는 다음과 같습니다:

낮은 노이즈, 높은 시그널, 단계별 파일 읽기 (low noise, high signal, staged file reads)

더 큰 변경 사항의 경우, 워크플로우를 다음과 같이 분할해야 합니다:

1. 서비스 동작 + OpenAPI 2. API 테스트 + 공유 유틸리티 3. 배포 영향 + 검증

이러한 접근 방식은 컨텍스트 윈도우(context window)가 작은 로컬 에이전트에게 유효하며, 클라우드 에이전트가 정밀함을 유지하는 데에도 도움이 됩니다.

QA 팀이 이를 도입하는 방법
작게 시작하십시오:

• 항상 현재 작업 컨텍스트 (task context)를 읽도록 하는 규칙을 담은 AGENTS.md를 추가하십시오.
• 활성 티켓 (active ticket)을 위한 contexts/current/service-context.yml을 추가하십시오.
• 저장소 레이아웃 (repo layout)과 OpenAPI로부터 resolved-context.yml을 생성하십시오.
• 하나의 압축된 API 테스트 플레이북 (API-test playbook)을 추가하십시오. 이 저장소에서는 SKILL.md로 저장됩니다.
• 지원되지 않는 기대 사항 (unsupported expectations)을 위한 QA 격차 프롬프트 (QA gap prompt)를 추가하십시오.
• 컨텍스트 토큰 (context tokens)과 검증 통과율 (verification pass rate)을 측정하십시오.

수백 개의 서비스를 수동으로 목록화하는 것부터 시작하지 마십시오. 저장소 컨벤션 (repo conventions), OpenAPI, 그리고 소스 파일이 안정적인 사실을 제공하도록 하십시오.

이것이 증명하는 것
이것은 QA의 판단, CI, 코드 리뷰 (code review), 또는 프로덕트 오너십 (product ownership)을 대체하는 것이 아닙니다.

이는 더 좁지만 유용한 점을 증명합니다:

테스트 의도 (test intent), 저장소 토폴로지 (repo topology), 계약 증거 (contract evidence), 그리고 검증 (verification)이 명시적일 때, 에이전트는 API 자동화에 있어 더욱 유용해집니다.

로컬 에이전트 (Local agents)는 실험 비용을 낮추고 투명성을 높입니다. 클라우드 에이전트 (Cloud agents)는 더 강력한 추론 (reasoning)과 더 큰 컨텍스트 (context)를 위해 동일한 워크스페이스 패턴을 사용할 수 있습니다.

이 프레임워크는 본질적으로 QA 규율 (QA discipline)에 관한 것입니다: 에이전트에게 경로를 안내하고, 테스트 의도를 보호하며, 결과를 검증하고, 격차를 숨기는 대신 보고하십시오.

*참고 및 한계
*_

검증 (Verification)은 단순히 테스트를 통과(green)시키는 것만이 아닙니다. 루프 (loop)는 QA 신호 (QA signal)를 보존하고, 계약 증거 (contract evidence)를 검증하며, 기대 사항이 지원되지 않을 때 프로덕트 격차 (product gaps)를 보고해야 합니다.

저는 이 글을 표준적인 에이전트 기반 개발 프레임워크 (agentic-development framework)를 정의하려는 사람이 아니라, API/UI 자동화 프레임워크를 직접 구축하고 유지 관리해 온 시니어 SDET의 관점에서 작성하고 있습니다.

이 워크스페이스는 일상적인 테스트 작업에서 비롯되었습니다. 즉, 반복적인 API 자동화 변경, 공유 유틸리티의 드리프트 (drift), 누락된 OpenAPI 체크, 그리고 에이전트가 실제 QA 시그널 (QA signal)을 놓치면서 테스트만 통과하게 만들 위험성 등이 포함됩니다. 또한 저는 컴팩트한 지침 파일 (compact instruction files), 명시적인 컨텍스트 라우팅 (explicit context routing), 루프 스타일 검증 (loop-style validation)과 같이 에이전트 워크플로에서 흔히 사용되는 패턴들로부터 아이디어를 빌려왔습니다.

따라서 이것은 실용적인 참조 구현체 (reference implementation)이며, 보편적인 정답은 아닙니다. 어떤 프로젝트에는 이러한 구조가 필요하지 않을 수도 있습니다. 어떤 프로젝트는 다른 리포지토리 토폴로지 (repo topology), 테스트 프레임워크, 모델 또는 컨텍스트 리졸버 (context resolver)가 필요할 수도 있습니다. 적응시켜야 할 중요한 아이디어는 바로 규율 (discipline)입니다. 즉, 작업 컨텍스트 (task context)를 작게 유지하고, 소스 및 계약 (contracts)으로부터 안정적인 사실을 도출하며, 리포지토리 소유권을 명시하고, 결과를 검증하는 것입니다.

읽어주셔서 감사합니다. 여러분의 생각이나 피드백, 또는 이 프레임워크를 더욱 개선하기 위한 아이디어를 듣고 싶습니다.