Agentic Engineering 이란

Agentic Engineering은 다음 요소들을 하나의 시스템으로 묶는다.

목표 정의
→ 작업 분해
→ 컨텍스트 제공
→ 도구 연결
→ 에이전트 실행
→ 자동 검증
→ 인간 승인
→ 배포/반영
→ 관측/감사
→ 피드백 축적

Agent는 단순 챗봇이 아니라 도구·상태·오케스트레이션을 가진 실행 시스템이다.

Vide Coding과의 차이점

Anthropic은 agentic system에 대해 다음과 같이 설명한다.

• 목표를 향해 어느 정도 자율적으로 행동하고 코드베이스를 읽고 계획하고 도구를 사용하고 결과를 평가하며 접근 방식을 조정한다

Agentic Engineering의 본질은 다음과 같다고 할 수 있다.

AI가 코드를 작성하게 하는 것이 아니라, AI가 작성한 코드가 시스템에 안전하게 들어올 수 있는 생산라인을 만드는 것.

Agentic Engineering에 필요한 역량

1. 요구사항 분해 능력

• 요구사항을 명확한 작업 단위로 쪼개는 능력

나쁜 예시:

회원가입 기능을 구현해줘.

좋은 예시:

Auth에 회원가입 기능을 구현한다.

조건:
- username, email, password를 입력받는다.
- email은 중복될 수 없다.
- password는 BCrypt로 단방향 해시한다.
- 기본 권한은 ROLE_USER로 고정한다.
- 클라이언트가 role을 넘겨도 무시한다.
- 회원가입 성공 시 user_id, email, created_at만 반환한다.
- 비밀번호는 응답에 포함하지 않는다.
- 중복 이메일이면 409를 반환한다.
- 단위 테스트와 통합 테스트를 작성한다.

Agent에게 큰 목표만 전달하는 것이 아니라, 수행 조건, 금지 조건, 성공 조건, 테스트 조건을 전달해야 한다.

2. 컨텍스 엔지니어링 능력

Software 3.0에서 핵심 조작 대상은 코드만이 아니라 context window이다.

Karpathy는 Software 3.0을 prompt, context, tools, examples, memory, instructions로 LLM을 프로그래밍하는 세계로 설명한다.

Agentic Engineering에서 컨텍스트는 사실상 프로그램의 일부이다. 좋은 결과를 위해서 agent에게 필요한 컨텍스트는 다음과 같.

이걸 매번 프롬프트에 쓰는 것이 아니라 프로젝트에 문서화해야 한다. (하네스)

Codex는 AGENTS.md를 읽어 프로젝트별 지침을 적용할 수 있고, 이 파일에는 코드베이스 탐색 방법, 테스트 명령어, 프로젝트 표준 관행 등을 넣을 수 있다. OpenAI도 Codex가 좋은 개발 환경, 신뢰 가능한 테스트 구성, 명확한 문서가 있을 때 더 잘 작동한다고 설명한다.

이에 따라 아래와 같은 구성이 필요하다고 할 수 있다.

AGENTS.md
docs/architecture/overview.md
docs/architecture/service-boundaries.md
docs/domain/glossary.md
docs/security/security-policy.md
docs/testing/test-strategy.md
docs/deploy/deployment-flow.md
docs/adr/
.agents/skills/

• AGENTS.md에는 너무 많은 내용을 넣지 않고 반드시 지켜야 할 핵심 규칙과 참조 문서 위치를 넣는 것이 좋다.

  • 예시:

    # AGENTS.md
    
    ## Project Summary
    This repository is an Auth-Service for an MSA-based platform.
    
    ## Tech Stack
    - Java 21
    - Spring Boot
    - Spring Security
    - Oracle
    - Redis Session
    - MyBatis or JPA depending on module
    
    ## Required Checks
    Before opening a PR:
    - Run unit tests
    - Run integration tests if persistence logic changed
    - Run static analysis
    - Confirm no secrets are printed
    
    ## Architecture Rules
    - Controller must not access Repository directly.
    - Entity must not be exposed as API response.
    - Role must not be accepted from public signup request.
    - Payment identity must be linked by internal user_id, not email.
    
    ## Important Docs
    - docs/architecture/service-boundaries.md
    - docs/security/security-policy.md
    - docs/testing/test-strategy.md
    

3. 검증 가능성

Agentic Engineering에서 가장 중요한 부분이다.

Karpathy는 “전통적 소프트웨어는 명세할 수 있는 것을 자동화하고, LLM과 강화학습은 검증할 수 있는 것을 자동화한다”고 설명한다. 코딩 에이전트가 빠르게 좋아지는 이유도 테스트 통과/실패, 프로그램 실행/크래시, diff 검토, benchmark 측정 같은 피드백이 있기 때문이다.

agent에 작업을 맡기기 전에 “이 작업의 성공 여부를 자동으로 확인할 수 있는가?” 를 생각해야 한다. 검증이 안된다면 작업에 대한 품질을 보증할 수 없다.

필요한 역량은 아래와 같다.

테스트는 품질 보조 수단이라기 보다 agent의 작업 방향을 잡아주는 reward signal이다.

4. 도구를 안전하게 연결하는 능력

Agent가 실제 작업을 하려면 여러 도구가 필요하다.

MCP는 외부 시스템을 AI 도구와 연결하기 위한 표준 중 하나이다. Anthropic은 MCP를 다음과 같이 설명한다.

Anthropic MCP는 AI 시스템과 데이터 소스 사이의 안전한 양방향 연결을 만들기 위한 open standard로 설명한다. MCP 서버를 통해 Google Drive, Slack, GitHub, Git, Postgres, Puppeteer과 같은 시스템을 연결할 수 있다고 한다. MCP의 tool 개념은 language model이 외부 시스템에 질의하거나 API를 호출하거나 계산을 수행할 수 있게 하는 인터페이스이다. 각 tool은 이름과 schema metadata를 가진다.

도구 연결에 있어서 중요한 부분은 “연결”보다 권한 통제이다. 권한 통제를 위해 필요한 역량은 아래와 같다.

무분별한 권한 부여보다 작업별 최소 권한 도구를 주는 것이 중요하다. 실무에서도 각 개발자들에게 모든 권한을 주거나 DB의 마스터 계정을 사용하기도 하는데, 개발단계에서 권한을 잘 설계해왔다면 Agent 권한 설계에 대한 부분도 어렵지 않게 진행할 수 있을 것 같다.

5. 가드레일과 Human in the loop 설계 능력

OpenAI Agents SDK 문서에서는 guardrail을 input, output, tool invocation 주변의 체크와 검증으로 설명한다. 즉 agent가 사용자의 입력, 최종 출력, 도구 호출 전후에서 정책 위반이나 위험한 행동을 막을 수 있게 하는 것이다.

또한 OpenAI 문서는 guardrail과 human review를 함께 사용해 workflow가 계속 진행될지, 멈출지, 중단될지 결정할 수 있다고 설명한다. 특히 취소, 수정, shell command, 민감한 MCP action 같은 side effect가 있는 작업은 human-in-the-loop approval을 둘 수 있다.

전체권한, 기본권한, 자동검토 옵션이 있는데 필요에 따라 옵션을 잘 설정하는 것이 중요하다고 생각된다. 예를 들어서 아래와 같이 설계를 진행할 수 있다.

6. 아키텍처와 코드 리뷰 능력

AI가 코드를 만들수록, 사람에게 더 중요한 것은 아키텍처 판단이다. 세부적인 설계 없이 구현을 진행하면 아래와 같은 문제가 발생할 수 있다고 한다.

- Controller에서 Repository 직접 호출
- DTO와 Entity 혼합
- 보안상 받으면 안 되는 필드를 request DTO에 포함
- email 같은 변경 가능한 값으로 결제/권한 identity 연결
- transaction boundary 부적절
- DB unique constraint 없이 service 코드에서만 중복 검사
- N+1 query 발생
- 임의 dependency 추가
- 기존 공통 모듈 무시하고 새 유틸 생성
- 예외 처리 방식 불일치
- 테스트는 통과하지만 운영 구조와 맞지 않는 코드 작성

요즘에는 모델들이 워낙 좋아져서 대부분의 문제는 발생하지 않았던 것 같다. “공통 모듈 무시”과 같은 문제는 코드 베이스가 큰 프로젝트에서 규칙 없이 구현을 실행할 때 발생하기도 했었다. 패키지 구조에 대한 명확한 규칙이 없을 경우, 한 패키지에 클래스와 인터페이스들이 몰리는 문제도 발생한다.

Agentic Engineering에서 사람은 “코드 타이퍼”가 아니라 시스템 불변조건을 지키는 설계자가 되어야 한다고 한다.

7. Observability와 Trace 해석 능력(관측 가능성, 추적)

agent가 작업을 수행한 후 의문점이 생길 수 있다.

왜 이 파일을 수정했지?
왜 이 dependency를 추가했지?
어떤 테스트를 실행했지?
어떤 에러를 봤지?
어떤 명령어를 실행했지?
어떤 도구를 호출했지?
누가 승인했지?
어느 시점부터 잘못됐지?

OpenAI Agents SDK의 tracing은 agent run 동안 LLM generation, tool call, handoff, guardrail, custom event 등을 기록해 개발 및 운영에서 workflow를 디버깅, 시각화, 모니터링할 수 있게 한다.

Agentic Engineering에서는 agent 실행 로그가 단순 로그가 아니라 감사 자료이자 품질 증거다.

필요한 로그는 다음과 같다.

agent_run_id
task_id
input_spec_version
loaded_context_files
used_tools
executed_commands
modified_files
test_results
security_scan_results
approval_events
created_branch
created_pr
deployment_target
rollback_result
final_summary

OpenAI의 Github에 접속해보면 Euphony 프로젝트를 확인할 수 있다. 로컬에서 실행해보면 Codex의 세션들을 확인해볼 수 있다. 각 세션 진입 시 사용자와의 대화와 Codex 실행 이력에 대한 로그를 볼 수 있다.

8. 보안 역량

Agentic Engineering에서 보안은 선택 사항이 아니다. 오히려 기존 개발보다 더 중요하다고 한다.

agent는 사람이 한 번에 할 수 없는 작업을 빠르게 수행할 수 있기 때문이다. 위험 요소는 다음과 같다.

반드시 필요한 것

- sandbox execution
- network 제한
- secret masking
- read/write 권한 분리
- branch protection
- mandatory PR review
- dependency allowlist
- security scan
- test weakening detection
- migration approval
- production deploy approval
- audit log

실제로 OpenAI의 리포트에 따르면 CoT 문제를 확인할 수 있다.

해당 리포트는 CoT(Chain of Thought)를 안전 모니터링에 활용하는 방식에서 발견한 문제를 공개한 것이다.

리포트 핵심 내용은

“모델이 나쁜 행동을 하려는 생각을 CoT에 드러내는 능력은 안전상 매우 유용하므로, 훈련 중 그 ‘나쁜 생각’을 직접 벌점 처리하면 안 된다”

이다.

https://alignment.openai.com/accidental-cot-grading/

내용 자체는 모델 검증에 대한 내용이다. 이 리포트를 통해 보안 역량에 대해 전달하고자 하는 바는, 모델이 우회를 진행한다는 것이다. 리포트에 따르면 모델은 보상을 위해 잘못된 행동을 멈추는 대신, 작업 의도를 CoT에 숨기도록 학습됐다고 한다. 시스템 자체에 대한 보안도 중요하지만 이렇게 모델에 관련된 보안도 모니터링을 진행할 필요가 있다고 생각된다. 위에서 언급한 Euphony가 모델 작업에 대한 모니터링 도구로 유용하게 사용될 수 있다.(OpenAI 모델 한정)

Agentic Engineering에서 꼭 필요한 구성요소

이 파트는 사람이 아니라 시스템에 반드시 있어야 할 것들을 정리한 것이다.

1. Agent 작업 명세서

모든 agent 작업은 자유로운 프롬프트가 아니라 작업 명세서로 시작해야 한다.

# Agent Task Spec

## Goal
무엇을 구현/수정할 것인가?

## Background
왜 필요한가?

## Scope
수정 가능한 범위는 어디까지인가?

## Out of Scope
하지 말아야 할 것은 무엇인가?

## Constraints
기술적/보안적/아키텍처 제약은 무엇인가?

## Acceptance Criteria
완료 조건은 무엇인가?

## Required Tests
어떤 테스트를 작성/실행해야 하는가?

## Risk
주의해야 할 위험은 무엇인가?

## Human Approval Required
어떤 작업에서 사람 승인이 필요한가?

이런 명세서를 통해 agent를 “검증 가능한 방향”으로 이끌어야 한다.

2. Agent용 프로젝트 지침 파일

필수 파일은 최소 아래 정도이다.

AGENTS.md
docs/architecture/overview.md
docs/architecture/service-boundaries.md
docs/domain/glossary.md
docs/security/agent-permission-policy.md
docs/testing/test-strategy.md
docs/deploy/deployment-flow.md
docs/adr/

Codex는 AGENTS.md 를 계층적으로 읽고, global guidance와 project-specific guidance를 합쳐 일관된 기대치를 적용할 수 있다. OpenAI 문서에 따르면 Codex는 global scope, project scope, current directory까지 instruction chain을 구성하며, 가까운 디렉토리의 지침이 나중에 포함되어 앞선 지침을 override하는 방식으로 작동한다.

MSA 프로젝트라면 서비스별로 지침을 나눠서 작성하는 것이 좋다.

AGENTS.md

services/
  auth-service/
    AGENTS.md
  payment-service/
    AGENTS.md
  service-api/
    AGENTS.md
  frontend/
    AGENTS.md

예를 들어 payment-service/AGENTS.md 에는 다음과 같은 규칙이 들어가야 한다.

## Payment Service Rules
- Payment identity must be linked by internal user_id.
- Never trust email as the payment-account binding key.
- Never log payment provider secrets.
- Payment webhook verification is mandatory.
- Add integration tests for payment state transitions.

3. Skill / Workflow 패키지

반복되는 작업이나 정확히 수행 방법이 있는 작업은 매번 프롬프트를 쓰면 비효율적이다. 이 경우 skill로 만들어서 사용하는 것이 좋다.

OpenAI Codex의 Agent Skills는 task-specific capability를 추가하기 위한 방식이며, skill은 SKILL.md, 선택적 script, reference, asset 등을 포함할 수 있다. Codex는 skill 설명을 보고 필요한 경우 전체 SKILL.md를 읽는 progressive disclosure 방식으로 context를 효율적으로 사용한다.

전체 인프라 관리를 하는 경우, 아래와 같이 skill을 만들 수 있다.

.agents/skills/
  spring-controller-review/
  mybatis-query-review/
  oracle-index-check/
  spring-security-review/
  redis-session-review/
  dockerfile-hardening/
  jenkinsfile-review/
  sonarqube-fix/
  gitlab-ci-review/
  k8s-manifest-review/
  nginx-config-review/

세부적으로 spring-security-review/SKILL.md에 대한 역할은 아래와 같이 작성할 수 있다.

name: spring-security-review
description: 스프링 부트(Spring Boot) 환경에서 인증, 인가, 세션, CORS, CSRF, 비밀번호 처리와 관련된 코드를 리뷰할 때 사용합니다.
Check:

비밀번호 해싱: 비밀번호는 반드시 단방향 해시 알고리즘을 사용하여 저장해야 합니다.

회원가입 필드 제한: 누구나 접근 가능한 공개 회원가입 API에서는 권한(role)이나 관리자(admin) 관련 필드를 입력받아서는 안 됩니다.

세션 고정 공격 방지: 세션 고정(Session fixation) 보호 기능이 활성화되어 있어야 합니다.

접근 권한 제어: 민감한 데이터를 다루는 엔드포인트에는 명시적인 인가(Authorization) 규칙이 설정되어야 합니다.

CORS 정책: 운영(Production) 환경의 CORS 설정에서 임의의 출처(Origin)를 허용(* 등)해서는 안 됩니다.

로그 보안: 인증 실패 로그에 비밀번호나 토큰 같은 자격 증명(Credentials) 정보가 노출되어서는 안 됩니다.

이렇게 AI 개발에 대한 표준을 만들어 다른 에이전트를 사용하더라도 일정한 결과물을 얻을 수 있다.

4. 격리된 실행 환경

Agent가 직접 로컬이나 개발 서버에서 작업하면 위험할 수 있다. 격리된 작업 공간을 사용하는 것이 권장된다.

- task별 isolated workspace
- branch 또는 git worktree 분리
- container 기반 실행
- 제한된 network
- mock 또는 test DB 사용
- secret 없는 환경
- 테스트용 credential만 제공

OpenAI의 Codex 소개에서도 각 task가 codebase가 preload된 별도 isolated environment에서 처리되고, 파일을 읽고 수정하고 테스트, linter, type checker 같은 명령을 실행할 수 있다고 설명한다. 또한 terminal log와 test output을 통해 작업 근거를 확인할 수 있고, 사용자가 결과를 리뷰한 뒤 PR 생성이나 통합을 할 수 있다고 설명한다.

5. 자동 검증 파이프라인

Agentic Engineering의 생산 라인은 아래와 같이 구성하는 것이 좋다. (이미지 배포 환경 예시)

Agent 작업 완료
→ format
→ lint
→ unit test
→ integration test
→ build
→ SAST
→ dependency scan
→ secret scan
→ SonarQube
→ PR 생성
→ 사람 리뷰
→ merge
→ GitLab mirror
→ GitLab Runner build
→ image scan
→ registry push
→ staging deploy
→ smoke test
→ 승인
→ production deploy

개발 단계는 lint , CI 과정은 SonarQube , 최종 작업에는 Codex Review와 같은 기능을 사용하면 좋을 것 같다.

6. 승인 게이트

모든 것을 자동화하는 것보다 개발자 검토와의 균형이 중요하다고 생각된다.

Agentic Engineering에서는 승인 게이트를 명확히 둬야 한다.

자동 진행 가능:
- 코드 읽기
- 테스트 생성
- feature branch 수정
- PR 생성
- 문서 초안 작성
- 로그 분석
- 실패 원인 후보 정리

승인 필요:
- dependency 추가
- DB schema 변경
- 인증/인가 로직 변경
- 결제 로직 변경
- 운영 설정 변경
- Jenkins/GitLab CI 설정 변경
- Dockerfile base image 변경
- 배포 실행
- 서버 restart
- main merge

원칙적으로 금지:
- 운영 secret 조회
- 운영 DB 직접 수정
- 테스트 삭제로 통과 처리
- 보안 검사 비활성화
- branch protection 우회

OpenAI의 guardrail/human review 문서도 side effect가 있는 shell command나 민감한 MCP action에는 human-in-the-loop approval을 둘 수 있다고 설명한다.

7. 감사 로그와 증거 기반 리뷰

Agent가 만든 PR에는 일반 PR보다 더 많은 검증이 필요하다. 이를 염두에 둔 PR 템플릿 예시이다.

## Agent Summary
무엇을 변경했는가?

## Requirement Mapping
어떤 요구사항을 만족하는가?

## Files Changed
주요 변경 파일과 이유

## Tests Run
- [ ] Unit tests
- [ ] Integration tests
- [ ] Build
- [ ] Lint
- [ ] Security scan

## Evidence
테스트 결과, 로그, 스크린샷, benchmark 등

## Risk
위험한 변경 사항

## Human Review Points
사람이 반드시 봐야 하는 부분

## Rollback Plan
문제 발생 시 되돌리는 방법

이렇게 정리되어야 제대로, 좀 더 빠르게 검토할 수 있다.