AI 에이전트를 개발할 때 효율적인 프로젝트 트리 구조를 만드는 방법

AI 에이전트 개발에서 프로젝트 트리 구조는 단순한 폴더 정리가 아닙니다. 에이전트가 어떤 문서를 읽고, 어떤 도구를 실행하며, 어떤 산출물을 남기고, 어떤 기준으로 검증할지를 정하는 운영 설계에 가깝습니다. 구조가 흐리면 에이전트는 매번 전체 저장소를 다시 해석해야 하고, 사람도 어디를 고쳐야 하는지 찾기 어려워집니다.

특히 Codex처럼 로컬 코드, 문서, 셸 명령, 테스트를 함께 다루는 개발 에이전트를 기준으로 보면 프로젝트 트리는 더 중요합니다. 한 에이전트가 모든 일을 하게 만들기보다 역할별 서브 에이전트와 작업 문서를 나누면 조사, 설계, 구현, 검증, 배포 판단을 분리할 수 있습니다.

1. 먼저 나눠야 할 기준

AI 에이전트 프로젝트를 만들 때 처음부터 복잡한 구조를 만들 필요는 없습니다. 다만 다음 네 가지는 초기에 분리해 두는 편이 좋습니다.

이 기준을 두면 “무엇을 고쳐야 하는가”와 “누가 참고해야 하는가”가 분리됩니다. 예를 들어 writer 역할을 바꾸고 싶을 때 `src/` 코드를 먼저 뒤질 필요 없이 `agents/writer.md`와 글쓰기 정책 문서를 먼저 확인할 수 있습니다.

2. Codex 기준의 기본 프로젝트 트리 예시

아래는 작은 AI 에이전트 프로젝트를 시작할 때 사용할 수 있는 기본 구조입니다. 특정 회사나 기존 프로젝트에 묶이지 않은 일반 예시입니다.

agent-project/
  AGENTS.md
  README.md
  pyproject.toml
  .env.example

  agents/
    researcher.md
    planner.md
    builder.md
    reviewer.md
    image-maker.md

  docs/
    policy/
      writing-policy.md
      security-policy.md
      image-guide.md
    workflows/
      draft-generation.md
      release-check.md
    decisions/
      2026-07-04-agent-tree.md

  prompts/
    research-brief.md
    implementation-brief.md
    review-brief.md

  src/
    agent_project/
      __init__.py
      cli.py
      config.py
      workflow.py
      tools/
        search.py
        file_ops.py
        renderer.py

  scripts/
    run_research.py
    run_draft.py
    run_review.py

  tests/
    test_workflow.py
    test_config.py
    fixtures/
      sample-topic.json
      sample-research.md

  output/
    .gitkeep

이 구조에서 `agents/`는 사람이 읽는 역할 정의입니다. `src/`는 실행 가능한 코드입니다. `docs/policy/`는 모든 에이전트가 지켜야 할 기준입니다. `output/`은 실행 결과가 쌓이는 임시 산출물 영역이므로, 중요한 원본 규칙이나 코드가 들어가면 안 됩니다.

3. 서브 에이전트는 폴더가 아니라 책임 단위로 나눈다

서브 에이전트 문서를 만들 때 흔한 실수는 이름만 나누고 실제 책임은 겹치게 두는 것입니다. 좋은 분리는 “입력, 판단 기준, 출력”이 다릅니다.

이렇게 정리하면 Codex에게 일을 맡길 때도 지시가 선명해집니다. “이 글을 써라”보다 “researcher는 출처와 쟁점을 정리하고, writer는 그 결과만 근거로 초안을 작성하고, reviewer는 정책 위반과 누락을 확인하라”가 훨씬 안정적입니다.

4. 작업 산출물은 output에 모으고, 기준 문서는 docs에 둔다

에이전트 프로젝트가 커질수록 산출물과 기준 문서가 섞이기 쉽습니다. 이 둘은 반드시 나눠야 합니다.

docs/
  policy/
    writing-policy.md
    image-guide.md

output/
  ai-001/
    research.md
    draft.md
    review.md
    images/
      plan.json
      figure-1.html
      figure-1.png

`docs/`는 반복해서 읽히는 규칙입니다. `output/`은 특정 작업의 결과입니다. 에이전트가 `output/`에 남긴 임시 판단을 다음 작업의 정책처럼 읽기 시작하면 글이나 코드에 이전 작업의 내용이 섞입니다. 따라서 에이전트 지시에는 “정책은 `docs/policy/`에서 읽고, 이전 작업 산출물은 같은 작업 ID 안에서만 참고한다”는 규칙을 넣는 것이 좋습니다.

5. Codex에서 쓰기 좋은 실행 흐름

Codex를 기준으로 하면 처음부터 완전 자동 실행보다 단계형 실행이 안정적입니다.

python scripts/run_research.py --task ai-001
python scripts/run_draft.py --task ai-001
python scripts/run_review.py --task ai-001

각 단계는 앞 단계의 산출물을 입력으로 받습니다.

topic.json
  -> researcher.md
  -> output/ai-001/research.md
  -> writer 또는 builder
  -> output/ai-001/draft.md
  -> reviewer.md
  -> output/ai-001/review.md

이 방식의 장점은 실패 지점을 찾기 쉽다는 점입니다. 조사 결과가 이상하면 writer를 의심할 필요가 없습니다. 이미지가 엉뚱하면 image-maker의 프롬프트 해석과 이미지 가이드를 보면 됩니다. 초안에 운영 메모가 노출되면 assembler 또는 reviewer 단계에서 공개 본문과 내부 메모를 제대로 분리했는지 확인하면 됩니다.

6. 작은 프로젝트와 큰 프로젝트의 차이

처음부터 엔터프라이즈 구조를 만들 필요는 없습니다. 규모에 따라 다음처럼 늘리면 됩니다.

작은 프로젝트

agent-project/
  AGENTS.md
  agents/
    researcher.md
    writer.md
    reviewer.md
  docs/
    writing-policy.md
  src/
  tests/
  output/

작은 프로젝트는 역할 문서와 정책 문서만 분리해도 충분합니다.

커지는 프로젝트

agent-project/
  agents/
    research/
      source-finder.md
      fact-checker.md
    build/
      backend-builder.md
      frontend-builder.md
    review/
      qa-reviewer.md
      security-reviewer.md

  docs/
    policy/
    architecture/
    operations/

  packages/
    web/
    api/
    workers/

프로젝트가 커지면 에이전트를 기술 영역별로 나누는 것이 좋습니다. 다만 처음부터 `research/source-finder.md`, `research/fact-checker.md`처럼 세분화하면 운영 부담이 커질 수 있으므로, 실제 반복 작업이 생긴 뒤 나누는 편이 낫습니다.

7. 피해야 할 구조

AI 에이전트 프로젝트에서 피해야 할 구조는 다음과 같습니다.

효율적인 트리는 폴더가 많은 트리가 아니라 판단 기준이 흔들리지 않는 트리입니다. 사람이 봐도 “정책은 여기, 역할은 여기, 실행 코드는 여기, 결과는 여기”라고 바로 알 수 있어야 합니다.

8. 바로 적용할 수 있는 작성 순서

새 AI 에이전트 프로젝트를 만든다면 다음 순서로 시작하면 됩니다.

1. `AGENTS.md`에 전체 작업 원칙을 적습니다.

2. `agents/`에 역할별 문서를 만듭니다.

3. `docs/policy/`에 반복 기준을 둡니다.

4. `src/`에는 실행 코드만 둡니다.

5. `output/`에는 작업별 산출물만 저장합니다.

6. `tests/fixtures/`에 샘플 입력과 기대 결과를 둡니다.

7. 한 번 실행한 뒤 헷갈리는 경로가 있으면 폴더를 늘리기보다 이름과 책임을 먼저 고칩니다.

이 순서를 따르면 프로젝트가 커져도 구조가 급격히 무너지지 않습니다. 에이전트가 참고할 문서와 사람이 검토할 산출물이 분리되기 때문에, 자동화 실패가 나도 어느 단계에서 문제가 생겼는지 추적하기 쉽습니다.

결론

AI 에이전트를 개발할 때 효율적인 프로젝트 트리 구조는 코드 정리보다 역할 정리에 가깝습니다. Codex 기준으로 보면 `agents/`, `docs/`, `src/`, `tests/`, `output/`을 분리하는 것만으로도 작업 흐름이 훨씬 안정됩니다.

핵심은 세 가지입니다. 첫째, 서브 에이전트는 이름이 아니라 책임으로 나눕니다. 둘째, 정책 문서와 작업 산출물을 섞지 않습니다. 셋째, 자동 실행보다 단계별 실행 결과를 남기는 구조를 먼저 만듭니다. 이 기준을 지키면 AI 에이전트 프로젝트는 작은 실험에서 반복 가능한 개발 체계로 넘어갈 수 있습니다.

참고 링크

아래 자료는 Codex와 에이전트 개발 구조를 더 확인할 때 참고할 수 있는 공식 문서입니다.

• OpenAI Codex 문서
• OpenAI Codex CLI 문서
• OpenAI Agents SDK 문서
• OpenAI Codex GitHub 저장소