인간과 로봇이 함께 일하는 데 도움이 되는 엔지니어링 실천과, 현재의 에이전트 워크플로에 대한 글.
소프트웨어 개발만큼 인공지능 (AI) 에 의해 크게 변한 분야도 드뭅니다. 과장된 기대와 잠재력은 어디에나 있지만, 구체적인 활용 사례는 아직 더 만들어져야 하고, 도입도 여전히 더디게 느껴집니다.
하지만 파괴적 혁신에 집착하고, 엔지니어들이 새로운 도구에 열려 있으며, 코드가 그 Large Language Models (LLM s) 와 직접 맞닿아 있는 분야에서는 이 그림이 꽤 다르게 보입니다. 2022년 초, ChatGPT가 대중에게 공개되기 몇 달 전부터 GitHub Copilot은 이미 제 에디터 안에 들어와 있었습니다. 그리고 그다음 2년 동안 AI는 주변적이지만 매일 쓰는 도구가 되었습니다. 글쓰기 작업에는 GPT-4(2023년 초, 이후 Claude 3.5 Sonnet), 코드 리뷰에는 GPT-4o(2024년 초부터), 심층 검색에는 o1-preview(2024년 말)를 사용했습니다. 또 OpenAI API를 통해 제품에도 이를 통합하기 시작했습니다. 예를 들어 Enchères Immo 에서 부동산 가치 평가를 생성하는 데 활용했습니다(GPT-4o mini).
2025년에 들어서야 일이 정말 가속했습니다. 명령을 실행하고 결과에 반응할 수 있는 AI 에이전트 는 채팅 패러다임에서 벗어났습니다. 더 이상 제안을 복사해 붙여넣을 필요가 없고, 테스트 실행 덕분에 환각은 줄었으며, 반복 주기도 훨씬 짧아졌습니다. 작년 말에는 에이전트가 다른 에이전트(subagents) 를 실행할 수 있게 되면서, 구조화된 워크플로와 관심사 분리에 완전히 새로운 가능성이 열렸습니다.
변화는 매우 두드러졌습니다. 2025년 초에는 제 코드 중 기계가 생성한 비율이 10% 미만이었습니다. 연말에는 약 50%가 되었고요. 지금, 2026년 초에는 대략 90%가 에이전트에 의해 생성됩니다. 그 대부분은 수동 수정조차 거의 없습니다. 많은 동료들에게서도 보이는 패턴이고, 업계 전반으로 확산되고 있습니다.
일상 업무에서 에이전트가 늘어나면서, 새로운 모델과 새로운 도구, 그리고 우연히 읽게 되는 블로그 글들에 계속 흔들리는 많은 시행착오도 함께했습니다.
Visual Studio Code에서 처음 실험한 뒤, 저는 Codex, Cursor, Claude Code 사이를 오가다가 결국 다시 돌아왔습니다. 제가 가장 좋아하는 에디터가 기능 면에서 따라잡았고, 모든 확장 기능이 있는 제 IDE에서 작업하는 것, 모델 제공자를 바꿀 수 있는 것(Cursor처럼), 그리고 분리된 프로필(예: 회사용과 개인용 설정 및 구독)을 쓰는 것보다 나은 건 없었습니다.
많은 사람들처럼 저 역시 강한 «prompt engineering» 단계도 거쳤습니다. 완벽한 프롬프트를 만들고, 프롬프트 라이브러리를 관리하고, 역할극을 시도하는 식이었죠(«당신은 경험 많은 시니어 개발자이고, 프로젝트를 속속들이 알며, 깔끔한 코드를 작성합니다»). 하지만 지금 제 워크플로는 작업 환경과 에이전트 자체를 구조화하는 데 훨씬 더 초점이 맞춰져 있어서, 제가 보통 쓰는 프롬프트는 이런 수준입니다.
이 기능을 구현해 주세요 https://github.com/bruits/project/issues/123
모델이 발전할수록, AI와 함께 일하는 일은 올바른 마법의 주문을 찾는 것이라기보다, 문서와 도구와 프로세스로 이루어진 환경을 구조화하여 AI가 효과적으로 일할 수 있게 만드는 일에 더 가까워지기 때문입니다.
가장 중요한 요소는 컨텍스트 관리입니다. 100k 토큰을 넘어서도 모델은 과부하가 걸리면 정밀도가 떨어지고,1 최근 모델일수록 코드베이스를 더 많이 탐색하고, 더 많은 도구를 사용하며, 더 많은 자기 성찰적 작업을 수행하는 경향이 있습니다. 프로젝트가 잘 구조화되어 있다면 엄청난 생산성을 내지만, 그렇지 않다면 빠르게 잡음으로 빠져드는 지름길이기도 합니다…1 – Claude를 만든 회사의 AI 컨텍스트 관리에 대한 좋은 자료 ☞ Rajasekaran P & al (2025). Effective context engineering for AI agents. Anthropic Source
⁂
AGENTS.md(및 그 변형인 CLAUDE.md, GEMINI.md 등)는 에이전트를 위한 중심 가이드이지만, 잘못 쓰이면 효과를 떨어뜨리고 2 첫 상호작용부터 컨텍스트를 막히게 만들 수 있습니다. 제가 본 실수들에는 언어/프레임워크 베스트 프랙티스를 파일에 잔뜩 넣거나,3 포매팅/린팅 규칙을 넣거나,4 중복된 문서를 넣는 것이 있습니다.5 2 – 이 연구 방법론에 완전히 만족하는 것은 아니지만, 크고 일반적인 AI 생성 AGENTS.md 파일이 아예 없는 경우보다 성능이 더 나쁠 수 있음을 보여줍니다 ☞ Gloaguen T & al (2026). Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? arXiv Source3 – 예를 들어 Elixir 웹 프레임워크 Phoenix는 새 프로젝트를 만들 때 510줄짜리 AGENTS.md를 생성합니다…4 – 에이전트는 비싸고 느리며 컨텍스트 창에 제한되지만, 현대적인 린터는 빠르고 신뢰할 수 있으며 에이전트도 이미 사용할 수 있습니다.5 – 이렇게 하면 파일이 방대해질 뿐 아니라, 불일치, 모순, 오래된 정보의 위험도 커집니다.
대신 잘 작동하는 것처럼 보이는 것은 간결한 파일입니다.6 짧은 개요, 몇 개의 핵심 명령,7 문서 링크, 그리고 보편적으로 적용 가능한 가드레일이 들어 있는 형태입니다.8 6 – 에이전트 컨텍스트를 개선하는 구체적 방법을 다룬 Claude 중심 글 ☞ Source ; 더 일반적인 관점이면서 최소주의를 더 강하게 밀어붙이고, 부풀어진 파일을 줄이기 위한 프롬프트도 제공하는 글 ☞ Source7 – 특히 전형적인 패키지 매니저를 쓰지 않을 때 유용합니다(예: npm 대신 pnpm). 에이전트가 아마 알아내긴 하겠지만, 이 힌트는 토큰과 시간을 아껴줍니다.8 – 일부 LLM s 는 지시가 관련 없다고 판단하거나 파일이 너무 길면 AGENTS.md를 무시할 수 있습니다. 예를 들어 Claude는 시스템 프롬프트에 다음과 같이 적고 있습니다. «important: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task.»
탄탄한 문서 SSoT와 기존 동작을 덮는 테스트(둘 다 아래에서 다룹니다)와 결합되면, 이것은 «progressive disclosure»를 만들어 냅니다.9 이를 통해 에이전트가 탐색을 통해 관련 컨텍스트를 점진적으로 발견할 수 있습니다.10 11 12 9 – 앞서 인용한 Anthropic 논문에서 빌려온 용어입니다. 이 정확한 개념 하나를 다루는 단일 동료 심사 연구는 없지만, 다음 자료들은 수렴하는 근거를 보여줍니다.10 – 전용 탐색 도구를 통해 저장소를 상호작용적으로 탐색하는 에이전트는, RAG로 미리 가져온 파일을 입력받은 같은 모델보다 3배 더 많은 이슈를 해결합니다 ☞ Yang J & al (2024). SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering. arXiv Source11 – 행동 전에 코드와 Git 기록을 점진적으로 탐색하는 에이전트는 Linux 커널 크래시에서 강한 기준선보다 유의미하게 더 좋은 성능을 냅니다 ☞ Ramneet S & al (2025). Code Researcher: Deep Research Agent for Large Systems Code and Commit History. ICLR 2026 Source12 – 자기 명확화와 컨텍스트 정착 단계는 고전적 프롬프팅 방법에 비해 긴 컨텍스트 이해를 유의미하게 개선합니다 ☞ Wang Y & al (2025). Self-Taught Agentic Long Context Understanding. AgenticLU Source
제 프로젝트 Sampo의 구체적인 예시는 다음과 같습니다.
# Agents GuideSampo is a Rust monorepo to automate changelogs, versioning, and publishing—even for monorepos across multiple package registries 🧭## Useful Commands```shcargo fmt --all # formatcargo clippy --all --all-targets # lintcargo test --all # test```## Useful Resources- In [CONTRIBUTING.md](./CONTRIBUTING.md) : [Quality Guidelines](./CONTRIBUTING.md#quality-guidelines) applies to agents and humans equally, [Getting Started](./CONTRIBUTING.md#getting-started) helps you understand the project structure, and [Philosophy](./CONTRIBUTING.md#philosophy) is the project’s north star.- The [README](./README.md) lists all crates, and per-crate READMEs (e.g. [sampo-core](./crates/sampo-core/README.md)) contain public API documentation, it should stay concise and user-facing.- [GitHub](https://github.com/bruits/sampo) Issues and PRs are the best place for implementation details, design discussions, and technical decisions.## Agent Guardrails- Do not create new documentation files to explain implementation.- Do not add external dependencies without justification. Prefer the standard library and existing utilities.- All code, comments, documentation, commit messages, and user-facing output must be in English.- New features or bug fixes should have a changeset generated by Sampo, see [CONTRIBUTING.md](./CONTRIBUTING.md#writing-changesets) for guidelines.
스킬은 특정 역량을 문서화하기 위한 보완 도구입니다. 반복되는 작업, 코드베이스의 특이점, 또는 에이전트 전용 지시 같은 것들 말입니다. 사용자가 직접 호출할 수도 있고(슬래시 명령), 관련 있을 때 에이전트가 자동으로 집어들 수도 있습니다.
간결하고 실행 가능하게 쓰이면, 스킬은 progressive disclosure를 잘 확장합니다. 하지만 의심스러운 관행도 많이 보입니다. 프레임워크별 스킬 수백 개를 내려받거나, 문서를 중복하거나, 그것을 안전 가드레일로 의존하는 경우입니다(이 부분은 뒤에서 더 다룹니다). 일반적으로 기억할 점은, 스킬 호출은 AGENTS.md보다 덜 신뢰할 수 있고,13 반복 호출은 관련 없는 작업에 토큰을 태워 컨텍스트를 막히게 만든다는 것입니다.13 – Vercel의 실험에서 인덱싱된 AGENTS.md는 스킬보다 더 좋은 성능을 보였습니다(100% 대 79%/53%). 문서가 항상 보이기 때문에, 트리거 정확도나 순서에 의존하지 않기 때문입니다 ☞ Source
구체적인 예로, Sampo로 changeset을 생성하는 스킬이 있습니다. 이것은 문서로 연결되고, CLI 프롬프트를 우회하는 비대화형 명령을 제공합니다. Sampo는 틈새 도구이기 때문에, 이런 스킬이 없다면 에이전트는 이 명령을 찾기 위해 시행착오를 반복하며 토큰을 낭비했을 것입니다.
---name: sampo-changesetdescription: Create or update changesets to describe public API changes, and trigger changelog generation and release planning.---[Sampo](https://github.com/bruits/sampo) is a tool to automate changelogs, versioning, and publishing. It uses changesets (markdown files describing changes explicitly) to bump versions (in SemVer format), generate changelogs (human-readable files listing changes), and publish packages (to their respective registries).See [CONTRIBUTING.md](/CONTRIBUTING.md#writing-changesets) for changeset redaction guidelines.## Creating New ChangesetsTo create a changeset non-interactively:```shsampo add -p <package> -b <bump> -m "<description>"```Where <bump>ismajor, minor, or patch. Use -pmultiple times to target several packages. Prefix with the ecosystem to disambiguate:-p cargo/my-crate. When changesets.tagsis configured, use-t <tag>to categorize the changeset.## Updating Existing ChangesetsPending changesets are stored in the.sampo/changesetsdirectory. You can edit these markdown files directly, as long as you follow the guidelines above and Sampo format (read.sampo/changeset.md.example for reference).
제 생각에, 대부분의 과도한 프롬프팅은 결국 좋지 않은 컨텍스트 관리와, 모델이 효과적으로 일하려면 세세한 손잡이가 필요하다는 잘못된 가정으로 귀결됩니다. 실제로는 구조화된 환경에 잘 적응하고, 양질의 코드를 내는 능력은 새 릴리스가 나올 때마다 훌쩍 뛰어오릅니다. 어떤 마법의 프롬프트도 Claude 8이나 Codex 6에 접근하게 해주지는 않습니다… 때로는 정반대이기도 하고요.
⁂
그렇다면 저는 현재 모델들에서 어떻게 최대한의 효과를 끌어낼까요?
제 워크플로의 핵심 아이디어는 구조화된 사이클을 조율하는 조정 에이전트(Supervisor) 입니다. 이 에이전트는 각각 특정 역할에만 제한된 전문 하위 에이전트를 필요에 따라 반복적으로 호출합니다.
하나 이상의 Analysts 가 이슈를 읽고,14 코드베이스를 탐색하며, 어떤 것도 수정하지 않은 채 실행 가능한 브리프를 만들기 위해 기술적 컨텍스트를 찾아냅니다. 코드를 쓸 수 있는 유일한 에이전트인 Builder 는 프로젝트 관례를 따르며 이를 구현합니다. 그다음 Reviewer 가 diff를 평가하고 비판점을 제기합니다. 마지막으로 Fixer 가 자신이 가진 모든 도구(테스트, 디버깅, 코드베이스 검색 등)를 사용해 판단합니다. 수정 필요(→ Builder로 돌아감), 부적절함(→ 무시), 또는 모호함(→ 사용자에게 질문).14 – 에이전트의 도움을 받든 아니든, 이슈가 명확하고 이해관계자의 기대에 맞으며 범위가 적절히 잡혀 있는지 확인하는 일은 당신의 역할입니다.
장점은 세 가지입니다. 타깃팅된 컨텍스트(각 에이전트는 자신에게 관련된 브리프만 봄), 도구 제한(Reviewer는 파일을 수정할 수 없고, Builder는 GitHub를 건드릴 수 없음), 그리고 검증의 반복 루프(Reviewer → Fixer(s) → Builder) 입니다. 이 루프는 무언가를 구현하고 검증 없이 일이 끝났다고 간주하는 전형적인 «one-shot» 에이전트를 피하게 해줍니다.
다음은 Fixer용 하위 에이전트 프롬프트의 구체적인 예시입니다. 앞서 말했듯 컨텍스트 창의 잡음을 줄이기 위해, 그리고 실험을 거치며 쉽게 바꿀 수 있도록 최대한 단순하게 유지하려고 했습니다.
---name: Fixermodel: Claude Opus 4.6 (copilot)description: "Validates code review feedback by analyzing whether reported issues exist, then provides an honest verdict and minimal fix recommendations."tools: ["vscode","execute","read","edit","search","web","github/*","agent","todo"]---This agent validates a single code review critique, without making any code changes. It analyzes carefully whether the reported issue actually exists, and provides an honest verdict with minimal fix recommendations if needed.## Capabilities- Follow logic end-to-end, check assumptions and edge cases- Run tests and debugging to confirm or refute the reported issue- Check whether the critique falls within scope of a GitHub issue (if provided)- Compare with coding standards stated in AGENTS.md and CONTRIBUTING.md## Outputs- **Verdict**: Is the critique valid (fully/partly/not), and does it require a fix?- If needed, smallest safe fix recommendation and any open questions## Safety Rules- **Explicit order required**: Never push commits, open PRs, or create/modify issues.- **Production forbidden**: Never create, modify, or delete anything in production environments.
이 안전 규칙은 주로 에이전트가 원치 않는 행동을 반복 시도하지 못하게 하기 위한 것입니다. 앞서 말했듯, 고위험 행동을 막는 데 프롬프트에 의존해서는 안 됩니다(이 부분도 곧 다루겠습니다).
⁂
하위 에이전트의 격리된 컨텍스트는 MCP 서버처럼 강력하지만 토큰을 많이 먹을 수 있는 도구를 장착할 수 있게도 해줍니다. MCP 서버는 외부 도구(API, 데이터베이스, 파일…)를 에이전트에 노출하는 표준화된 서비스이며, Model Context Protocol (MCP) 을 사용합니다.
이 프로토콜은 에이전트에 특화된 형식으로 작성된 도구 설명과 응답을 통해 LLM을 안내합니다. 반면 CLI는 보통 모델에 최적화되어 있지 않아, 때때로 고된 시행착오를 유발합니다.15 또한 OAuth를 통한 인증을 표준화하여, 각 CLI가 갖는 제각각의 임시방편적 해법을 피하게 해줍니다. 권한도 더 세밀하게 설정할 수 있습니다.15 – Sentry 공동창업자의 흥미로운 글인데, MCP 도구의 진짜 가치는 steering 에 있으며, 원시 CLI는 이를 기본적으로 제공하지 않는다고 주장합니다. 그는 드리프트와 오용 위험을 줄이기 위해 이런 도구를 하위 에이전트 안에서 사용할 것도 권합니다 ☞ Source
제 하위 에이전트들 중 몇 개(특히 Analyst와 Fixer)는 Supervisor가 호출하여 이슈나 프로젝트 컨텍스트를 가져오게 할 수 있습니다(GitHub, GitLab, 또는 Linear MCP 서버를 통해). 문서 SSoT는 Notion MCP를 통해 가져오고, 더 좋은 경우 성능과 신뢰성 문제를 조사합니다(Sentry, HoneyComb, Datadog MCP 서버를 통해). 심지어 Snowflake MCP 서버를 통해 운영 데이터에 질의하기도 합니다. 하위 에이전트는 관련 정보만 반환하고, Supervisor는 이를 Builder의 컨텍스트에 주입합니다. 결과는 꽤 인상적입니다.
더 일반적으로, 유용한 도구는 실행 가능한 신호를 추출하면서 잡음과 왕복 횟수를 제한하는 도구입니다. 예를 들어 저는 점점 더 하위 에이전트가 ast-grep 을 사용하도록 제한하고 있습니다. 이것은 텍스트 전용 검색인 rg 나 grep 대신, 구문 구조를 기준으로 작동하는 코드 검색 및 변환 도구입니다. 더 빠르고, 더 신뢰할 수 있으며, 더 정확할 뿐 아니라, 대충 맞춘 정규식으로 고된 시행착오를 반복하는 대신 한 번의 왕복으로 복잡한 코드 변환도 수행할 수 있습니다.
또 다른 범주는 일반적인 개발 편의성과 관련됩니다. 현대적인 린터, 포매터, 테스트 러너, 그리고 사용자 정의 명령(예: 단일 패키지의 유닛 테스트만 실행하기) 같은 것들입니다. 끝이 안 보이는 테스트 스위트가 인간 기여자에게도 쓰이지 않듯, 빠르고 신뢰할 수 있는 도구는 에이전트에게도 더 많이 쓰일 뿐 아니라 반복 시간을 극적으로 줄여줍니다.
⁂
소프트 가드레일은 대부분의 에이전트 사용자에게 매우 자연스럽습니다. 프롬프트에 제한을 조금 추가하고, AGENTS.md에 몇 가지 규칙을 넣고, 출력은 사람이 수동으로 검토하는 식입니다. 하지만 이제는 에이전트의 규율에 의존하지 않고, 우리가 명시적으로 준비하지 않은 에이전트에게도 적용할 수 있는 수동적이고 결정적인 가드레일이 필요합니다.
물론 이미 갖춰진 자동화 가드레일 중 일부는 에이전트에도 그대로 작동합니다. CI 파이프라인, 브랜치 보호 규칙, 코드 오너, pre-commit hook 등이 그렇습니다. 하지만 에이전트 전용으로 설계된 새로운 것들도 추가할 수 있습니다. 예를 들어 Matt Pocock 의 이 preToolUse hook 는 위험한 Git 명령을 차단하고, 에이전트에 명확한 오류 메시지를 반환합니다.
#!/bin/bashINPUT=$(cat)COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')DANGEROUS_PATTERNS=( "git push" "git reset --hard" "git clean -fd" "git clean -f" "git branch -D" "git checkout \." "git restore \." "push --force" "reset --hard")for pattern in "${DANGEROUS_PATTERNS[@]}"; do if echo "$COMMAND" | grep -qE "$pattern"; then echo "BLOCKED: '$COMMAND' matches dangerous pattern '$pattern'. The user has prevented you from doing this." >&2 exit 2 fidoneexit 0
비슷하게, MCP 서버 같은 도구는 새로운 공격 표면도 도입합니다.16 따라서 잘 알려진 도구를 고르고, 권한을 세밀하게 설정하며(특히 쓰기 동작), 각 하위 에이전트를 실제로 필요한 도구로만 제한하는 것이 중요합니다. 예를 들어 Reviewer는 GitHub에 접근할 이유가 없고, Analyst가 Snowflake 질의를 해야 한다면 그것은 읽기 전용으로 제한되어야 합니다.16 – MCP 서버의 보안과 안전성을 다룬 흥미로운 논문이지만, 주로 그 서버를 만드는 개발자를 대상으로 합니다 ☞ Gaire S & al (2025). Systematization of Knowledge: Security and Safety in the Model Context Protocol Ecosystem. arXiv Source
아직 시도해보지 않았지만 유망하다고 보는 가드레일 두 가지는, LLM이 생성한 코드의 형식 검증과 에이전트 감사 추적의 정적 분석입니다. 첫 번째는 매우 활발한 연구 분야입니다. LLM s 는 형식 기법을 훨씬 더 접근 가능하게 만들 수 있고,17 증명 보조기는 테스트보다 엄격히 더 신뢰할 수 있는 검증 신호를 제공할 수 있습니다.18 두 번째는 hook과 결합한 에이전트의 기존 행동 로그를 활용하거나,19 LangFuse 와 LangSmith 같은 도구를 사용해 행동, 도구, 대화 로그를 분석함으로써 바람직하지 않은 행동 패턴이나 드리프트를 찾습니다.17 – LLM s 가 자연어 설명으로부터 형식 기법(Dafny, Nagini, Verus)을 합성할 수 있는지, 심지어 주류 언어까지 포함해 다룬 흥미로운 논문 두 편 ☞ Misu MRH & al (2024). Towards AI-Assisted Synthesis of Verified Dafny Methods. FSESource ; Shefer A & al (2025). Can LLMs Enable Verification in Mainstream Programming? arXiv Source18 – 증명 보조기가 주는 신호는 구성상 이진적이고 훼손될 수 없기 때문에, 코딩 에이전트를 이끄는 피드백 오라클로서 테스트보다 엄격히 우월합니다 ☞ Bayazıt B & al (2025). A Case Study on the Effectiveness of LLMs in Verification with Proof Assistants. LMPLSource19 – 예를 들어 Claude Code는 모든 행동을 ~/.claude/projects/ 에 JSONL로 기록하거나, preToolUse hook 를 사용해 사용자 정의 로그를 남길 수 있습니다. 그런 다음 이를 분석해 금지된 도구를 반복적으로 사용하려는 시도나, 사용되는 명령 유형의 드리프트 같은 바람직하지 않은 행동 패턴을 감지할 수 있습니다.
소프트웨어 개발자로서의 첫 5년 동안, 저는 빠르게 «코드를 말하는 사람» 유형을 알아봤습니다. 제품, 비즈니스, 아키텍처에는 별로 관심이 없지만, 코드베이스를 읽고, 문서화되지 않은 구조를 떠올리고, 테스트되지 않은 레거시 특이점을 기억하며, 경영진이 요구하는 대로 API s 를 엮어낼 수 있는 사람 말입니다.
하지만 AI가 코드베이스를 읽고, 설명하고, 문서를 쓰고, 자연어 지시를 받고, 기능을 구현하고, 디버깅하고, 자기 작업을 검증할 테스트까지 쓸 수 있게 된다면… 가치의 핵심이 바로 그 신비로운 줄들을 해독하는 능력에 있었던 개발자에게는 무엇이 남을까요?
다가오는 몇 년 동안, 이전 글 에서 제가 차별화 포인트로 설명했던 것들이 단지 새로운 기준선이 될지도 모릅니다. 비즈니스 요구사항에 기술적 통찰로 이의를 제기하고, 실행 가능한 타협안을 찾아 회사 내 정치를 헤쳐 나가며, 코드, 문서, 테스트, 인프라 등에 대한 관례를 정의하고 강제하는 일들 말입니다.
좋은 소식은, 그 사이에도 단순한 엔지니어링 실천만으로 우리의 영향력과 가치, 그리고 우리가 이미 쓰는 LLM 도구의 효과를 끌어올릴 수 있다는 점입니다.
⁂
에이전트와 인간이 함께 잘 일하도록 돕기 위해 할 수 있는 가장 좋은 일 중 하나는, 프로젝트의 single source of truth (SSoT) 로서 명확하고 간결하며 최신 상태의 텍스트 문서를 유지하는 것입니다. 각 섹션은 쉽게 접근할 수 있어야 하고, 분명히 식별된 소유자가 관리해야 합니다.
인간 기여자에게 SSoT 가 얼마나 강력한지에 대해서는 이미 좋은 글들 이 많이 있습니다. 하지만 에이전트를 위해서는, 이 소스가 이상적으로는 코드와 함께 존재하는 일반 텍스트 파일(Markdown, ADR s)이거나, 에이전트가 MCP 서버를 통해 접근할 수 있는 전용 서비스(예: Notion)여야 합니다. 읽기와 쓰기 같은 접근 권한도 세밀해야 해서, 에이전트, 개발자, 제품/문서 담당자, 디자이너가 각자 필요한 것만 볼 수 있어야 합니다.
핵심 포인트 중 하나는 중복을 피하는 것입니다. 에이전트, 기술 기여자, 비기술 이해관계자가 모두 같은 진실의 원천을 참고해야 하며, 서로 충돌하는 여러 버전을 만들어서는 안 됩니다. 간결함을 유지하고, 구현 세부사항은 피하며, 쉽게 낡는 정보는 가능한 한 적게 포함하는 것도 문서를 최신이고 관련성 있게 유지하는 데 도움이 됩니다.20 20 – 엔지니어에게는, 이해관계자를 위한 문서를 더 잘 쓰도록 도와주는 기술 문서 작성 강의가 많이 있습니다… 그리고 그것은 에이전트에게도 도움이 됩니다 ☞ Mintlify 의 예시와 더 큰 Google 자료를 참고할 수 있습니다.
제가 현재 충분히 활용하지 못하고 있는 도구들 중에는 SpecKit 이 있습니다. 이것은 살아 있는 명세와 생성된 코드 사이의 간극을 메우기 시작했고, 둘을 동기화하기 더 쉽게 만들어 줍니다. 그리고 infrastructure as code (예: Terraform) 도 살아 있는 문서의 좋은 예입니다. 에이전트가 쉽게 접근하고 수정할 수 있으면서, 운영 환경에 직접 영향을 줍니다.
⁂
같은 논리에서 환경을 구조화하는 차원에서, 테스트와 관측 가능성은 가장 가치 있는 가드레일 가운데 하나입니다.
TDD 지지자들에게는 놀랍지 않겠지만, 에이전트는 그 주장을 입증하고 있습니다. 테스트는 가끔 버그를 잡는 «있으면 좋은 것»이 아니라, 회귀를 막고 자신 있게 배포하기 위한 살아 있는 문서이자 «반드시 있어야 하는 것»입니다.21 소프트웨어가 커질수록, 테스트가 진실의 유일한 원천이 아니고서는 어떤 컨텍스트 창도, 어떤 인간의 기억도, 기대되는 모든 동작과 모든 엣지 케이스, 모든 비즈니스의 특이점을 담아둘 수 없습니다. 테스트는 또한 progressive disclosure를 강제합니다. 잘 테스트된 코드베이스에서 작업하는 에이전트는 실패하는 테스트에 부딪히고, 이를 고치기 위해 관련된 모든 컨텍스트를 발견하게 됩니다.21 – 대규모에서의 Google의 경험도 이 점을 확인합니다. 구현 세부가 아니라 관찰 가능한 동작에 초점을 맞춘 테스트는 코드가 진화해도 안정적으로 유지되며, 인간이든 아니든 어떤 기여자에게도 신뢰할 수 있는 신호가 됩니다 ☞ Winters T & al (2020). Software Engineering at Google, ch. 12 «Unit Testing». O’Reilly Source
관측 가능성은 그림을 완성합니다. 성능과 신뢰성을 위한 Service Level Objectives (SLO s) 는 모두가 무시하는 시끄러운 알림보다 훨씬 더 유용한, 명확하고 실행 가능한 신호를 제공합니다. 더 깊이 들어가면, 구조화된 로그와 메트릭은 문제를 진단하고 수정이 실제로 효과가 있는지 확인할 데이터를 제공합니다. 그리고 앞서 말했듯, 에이전트는 모니터링 스택에 연결된 MCP 서버를 통해 이 모든 것을 끌어올 수 있습니다.
무엇보다도, 둘 다 기여자의 규율과 무관한 수동적 가드레일로 작동합니다. 에이전트가 테스트 스위트를 실행하지 않았더라도 CI 파이프라인이 회귀를 잡아내고 머지를 막습니다. 개발자가 대시보드를 보는 걸 잊더라도, 알림은 여전히 울립니다. 점점 더 많은 코드가 자율적으로 생성되는 상황에서는, 이런 자동화된 안전망이 어떤 프롬프트보다 훨씬 더 중요합니다.
⁂
이런 안전망은 인간 기여자에게도 도움이 되지만, 더 많은 도구를 갖추고도 여전히 신뢰하기 어렵고 환각에 취약한, 점점 더 자율적인 에이전트에게는 더욱 중요해집니다. 그리고 모델은 빠르게 개선되고 있지만, 그 짧은 수명이라는 성격이 곧 바뀔 것이라는 징후는 없습니다. 에이전트는 호출되고, 그다음 버려집니다. 실행하고, 결과를 내고, 사라집니다. 자신이 한 행동의 결과를 인식하지 못한 채 말입니다. 책임은 이런 덧없는 존재에게 위임될 수 없고, 따라서 작업을 시작하게 한 엔지니어에게 남습니다.22 22 – AI가 코드 리뷰의 잡무를 자동화하더라도, PR은 여전히 개발의 사회적 계약이라는 흥미로운 글입니다. «Merge» 를 누르는 개발자가 책임을 집니다. 특히 아키텍처, 멘토링, 제품 결정에 대해서는 더욱 그렇습니다 ☞ Shwer E (2025). Code Review in the Age of AI. GitHub Blog Source
이것은 철학적인 각주가 아닙니다. 이 글에서 논의한 모든 가드레일(테스트, 관측 가능성, 도구 제한, 구조화된 리뷰)은 또한 전문가로서의 책임이기도 합니다. 내 대신 실행되는 것을 계속 통제하고,23 내가 배포하는 코드가 여전히 내 기준을 반영하도록 보장해야 하기 때문입니다.24 시스템이 점점 더 자동 조종으로 돌아갈수록, 이런 책임성은 루프 안에 인간을 남겨두는 핵심 이유 중 하나가 될지도 모릅니다.23 – AI의 도움을 받는 개발자는 유의미하게 덜 안전한 코드를 작성하면서도, 그 안전성에 더 큰 확신을 갖습니다. 이 연구와 사용된 모델은 다소 오래되었지만, 인간 리뷰가 단지 필요할 뿐 아니라 이전보다 더 까다로워졌음을 보여주는 «거짓 자신감 효과»를 입증합니다 ☞ Perry N & al (2023). Do Users Write More Insecure Code with AI Assistants? ACM CCSSource24 – 그런데 엔지니어링 기준만의 문제도 아닙니다…
에이전트 기반 개발은 새로운 위험을 도입하고, 그와 함께 새로운 책임도 가져옵니다. AI는 시니어 엔지니어에게 강력한 지렛대이지만, 주니어에게 주는 이점은 여전히 관찰하기 어렵습니다.25 더 나쁘게는, 이런 도구가 그들의 이해와 학습을 늦출 수도 있습니다.26 이는 가치가 단순한 코드 작성 능력보다 점점 더 깊은 아키텍처적·시스템적 이해에 놓이는 세상에서, 주니어 개발자를 어떻게 멘토링하고 성장시킬 것인가라는 시급한 질문을 던집니다. 25 – 시니어는 생산성을 높이고 새로운 영역으로 확장하지만, 주니어는 더 자주 도입함에도 측정 가능한 이점을 얻지 못합니다 ☞ Daniotti L & al (2026). Who is using AI to code? Science Source26 – AI 보조를 받은 개발자는 이해도에서 17% 낮은 점수를 받았고(특히 디버깅에서 감소폭이 큼), 새로운 기술 습득 속도도 느려졌으며, 특히 주니어에게서 두드러졌습니다. 다만 사용 방식에 따라 차이가 큽니다. AI에게 개념적 질문을 하는 사람들은 대조군과 비슷한 학습 수준을 유지했습니다 ☞ Shen J H & al (2026). How AI Impacts Skill Formation. Anthropic Source
좋은 면을 보자면, 에이전트가 일상적인 구현의 점점 더 큰 몫을 흡수한다면, 절약된 시간은 사라지지 않고 이동합니다. 더 어려운 대화 쪽으로요. 한 줄의 코드가 쓰이기 전에 모호한 요구사항에 이의를 제기하고, 레거시 코드베이스에서 주니어 개발자를 멘토링하고, 잘못된 문제를 푸는 제품 결정을 되밀어내고, 동료들과 함께 오후 한나절을 들여 아키텍처나 문서, 테스트 관례를 개선하는 일 말입니다. 그렇게 해서 내일은 에이전트와 인간 모두가 더 나은 일을 할 수 있게 되는 것입니다!
우리는 기술 혁명을 목격하고 있습니다. 엔지니어들은 신경망과 학습 방법을 만들었지만, LLM s 는 빠르게 우리의 이해를 벗어났습니다. 연구자들은 그 내부 작동을 더 잘 이해하여 더 잘 이끌기 위해 연구할 수 있겠지만, 우리 개발자에게는 무엇보다 실험과 시행착오, 발견의 시대입니다.
놀라운 발견은, 이 에이전트들이 얼마나 익숙한 존재로 드러나는가입니다. 마법 같은 프롬프트와 난해한 도구를 요구하기는커녕, 오히려 우리가 이미 알고 있던 좋은 엔지니어링 실천을 강화합니다. 문서가 부실하고, 테스트가 부족하며, 명확한 관례가 없는 코드베이스는 인간 기여자에게도 이미 문제였습니다. 에이전트는 그 부채를 더 비싸고 더 눈에 띄게 만들 뿐입니다.
그리고 모델은 계속 개선되겠지만, 인간 개발자에게 진정으로 가치 있는 것은 기술적인 것이 아니라 시스템적이고 정치적인 것입니다. 요구사항에 이의를 제기하고, 주니어를 멘토링하고, 아키텍처 결정을 지키고, 책임을 지는 일 말입니다. 코드 작성 너머에 자신의 사명이 있다고 믿는 소프트웨어 엔지니어에게는 무척 흥미로운 도전입니다.
오늘날 에이전트와 효과적으로 일한다는 것은 대부분 그들의 컨텍스트를 관리하고 잡음을 줄이는 일입니다. 이것은 인간에게도 좋은 조언입니다. 소셜 미디어가 주목을 끌고, 강의를 팔고, 청중을 모으고, 의제를 밀어붙이기 위해 잡음을 만들어내는 행위자들, 즉 AI 광신자이든 AI 파멸론자이든으로 넘쳐나는 시기이기 때문입니다. 우리는 구체적인 경험, 개인의 워크플로, 과학 논문, 솔직한 회고를 더 잘 드러내는 일을 더 잘할 수 있습니다.
물론 우려는 현실적입니다. 보안 위험, 이 새로운 환경에서 주니어의 불확실한 위치 등 말입니다. 그리고 시민으로서 저는 개인 데이터, 허위 정보, 선거 개입, 새로운 기술 독점에 대한 영향도 걱정합니다.27 27 – 이런 지정학적 분위기에서, 누구도 미국이나 중국의 빅테크에 더 의존하게 되는 일을 반기지 않습니다.
하지만 엔지니어에게, 특히 자신을 장인이나 빌더라고 부르는 사람들에게는, 지금은 짜릿하고 엄청나게 재미있는 순간입니다. 새로운 도구, 새로운 일하는 방식, 기술과 협업하는 새로운 방식. 새로운 모델 세대나 도구가 나올 때마다 워크플로는 흔들리고, 우리는 더 자유롭게 프로토타입을 만들고, 실험하고, 리팩터링할 수 있게 됩니다. 그리고 저장소가 잘 구조화되어 있다면, 그렇게 하면서도 높은 코드 품질을 유지할 수 있을지도 모릅니다!
앞으로 어떻게 전개될지 기대됩니다… 그리고 이 글로 다시 돌아와, 제 뻔한 실수와 형편없는 예측을 보며 웃게 되기를 바랍니다!
