Loading editor...
JSON Preview

{
  "type": "doc",
  "content": [
    {
      "type": "heading",
      "attrs": {
        "level": 1
      },
      "content": [
        {
          "type": "text",
          "text": "하네스 엔지니어링: Codex 에이전트 운영 노트"
        }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "이 예시 문서는 OpenAI의 "
        },
        {
          "type": "text",
          "text": "하네스 엔지니어링",
          "marks": [
            {
              "type": "bold"
            }
          ]
        },
        {
          "type": "text",
          "text": " 글을 바탕으로, 에이전트가 소프트웨어 제품을 빠르게 만들 수 있도록 사람이 어떤 환경과 피드백 루프를 설계해야 하는지 설명합니다. 여기서 하네스는 전기 배선이 아니라 "
        },
        {
          "type": "text",
          "text": "에이전트가 읽고, 실행하고, 검증하고, 반복할 수 있는 작업 환경",
          "marks": [
            {
              "type": "italic"
            }
          ]
        },
        {
          "type": "text",
          "text": "을 뜻합니다."
        }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "원문은 "
        },
        {
          "type": "text",
          "text": "OpenAI Engineering",
          "marks": [
            {
              "type": "link",
              "attrs": {
                "href": "https://openai.com/ko-KR/index/harness-engineering/",
                "target": "_blank"
              }
            }
          ]
        },
        {
          "type": "text",
          "text": "에 게시된 사례를 요약한 것입니다. 이 mock data는 editor/viewer 테스트용이므로 원문을 그대로 복제하지 않고, Tiptap extension 렌더링을 확인하기 좋은 내부 문서 형식으로 재구성했습니다."
        }
      ]
    },
    {
      "type": "blockquote",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "핵심 관점은 간단합니다. 사람은 더 적은 코드를 직접 쓰고, 더 많은 시간을 시스템의 경계, 도구, 문서, 검증 루프를 만드는 데 씁니다."
            }
          ]
        }
      ]
    },
    {
      "type": "heading",
      "attrs": {
        "level": 2
      },
      "content": [
        {
          "type": "text",
          "text": "1. 실험의 배경"
        }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "OpenAI 팀은 Codex가 대부분의 코드를 작성하는 방식으로 내부 베타 제품을 구축했습니다. 애플리케이션 로직뿐 아니라 테스트, CI, 문서, 관측 가능성, 내부 개발 도구까지 에이전트가 생성하도록 두었습니다. 사람은 구현 세부를 직접 타이핑하기보다 목표를 나누고, 제약 조건을 정하고, 결과를 검토하는 역할에 집중했습니다."
        }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "초기 리포지터리는 빈 상태에서 시작되었고, 스캐폴딩, 패키지 관리자, CI, 포맷 규칙, 에이전트 작업 지침까지 Codex가 만들어 냈습니다. 시간이 지나면서 리포지터리 자체가 에이전트가 이해하기 쉬운 형태로 진화했고, 사람이 작성한 코드가 아니라 사람이 설계한 운영 체계가 생산성의 중심이 되었습니다."
        }
      ]
    },
    {
      "type": "heading",
      "attrs": {
        "level": 2
      },
      "content": [
        {
          "type": "text",
          "text": "2. 엔지니어의 역할 변화"
        }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "에이전트 우선 환경에서 엔지니어는 "
        },
        {
          "type": "text",
          "text": "작업자",
          "marks": [
            {
              "type": "italic"
            }
          ]
        },
        {
          "type": "text",
          "text": "라기보다 "
        },
        {
          "type": "text",
          "text": "환경 설계자",
          "marks": [
            {
              "type": "bold"
            }
          ]
        },
        {
          "type": "text",
          "text": "에 가깝습니다. 큰 목표를 설계, 코드, 테스트, 검토 같은 작은 단위로 나누고, 에이전트가 스스로 다음 단계를 찾을 수 있도록 충분한 맥락과 실행 가능한 도구를 제공합니다."
        }
      ]
    },
    {
      "type": "bulletList",
      "content": [
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "목표를 작게 나누고 각 단계의 완료 조건을 명확히 쓴다."
                }
              ]
            }
          ]
        },
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "에이전트가 직접 쓸 수 있는 CLI, 스크립트, 브라우저 검증 도구를 제공한다."
                }
              ]
            }
          ]
        },
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "리뷰 피드백을 문서나 린트 규칙으로 남겨 다음 실행에도 재사용한다."
                }
              ]
            }
          ]
        },
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "에이전트가 실패하면 모델 탓만 하지 않고 누락된 구조와 도구를 찾는다."
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "type": "heading",
      "attrs": {
        "level": 2
      },
      "content": [
        {
          "type": "text",
          "text": "3. 애플리케이션을 에이전트가 읽을 수 있게 만들기"
        }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "사람의 QA 시간이 병목이 되면, 에이전트가 UI와 런타임 신호를 직접 관찰할 수 있어야 합니다. 예를 들어 각 git worktree마다 앱을 띄우고, 브라우저 스냅샷과 스크린샷을 수집하고, 로그와 메트릭을 쿼리할 수 있으면 Codex가 버그 재현부터 수정 검증까지 긴 루프를 스스로 수행할 수 있습니다."
        }
      ]
    },
    {
      "type": "orderedList",
      "attrs": {
        "start": 1
      },
      "content": [
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "변경 브랜치별로 격리된 앱 인스턴스를 실행한다."
                }
              ]
            }
          ]
        },
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "DOM 스냅샷, 스크린샷, 콘솔 로그를 에이전트 컨텍스트에 노출한다."
                }
              ]
            }
          ]
        },
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "서비스 로그, 메트릭, 트레이스를 로컬 관측 가능성 스택에 보관한다."
                }
              ]
            }
          ]
        },
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "수정 후 같은 사용자 여정을 다시 실행하여 회귀 여부를 확인한다."
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "type": "heading",
      "attrs": {
        "level": 2
      },
      "content": [
        {
          "type": "text",
          "text": "4. 리포지터리 지식을 기록 시스템으로 만들기"
        }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "원문에서 강조하는 중요한 교훈은 에이전트에게 거대한 설명서를 밀어 넣는 것이 아니라, 작은 지도와 잘 정리된 지식 베이스를 제공해야 한다는 점입니다. 짧은 AGENTS.md는 목차 역할을 하고, 실제 상세 정보는 docs 디렉터리 안의 설계 문서, 실행 계획, 품질 기준, 참조 자료로 분리됩니다."
        }
      ]
    },
    {
      "type": "codeBlock",
      "attrs": {
        "language": "txt"
      },
      "content": [
        {
          "type": "text",
          "text": "AGENTS.md\nARCHITECTURE.md\ndocs/\n  design-docs/\n  exec-plans/\n  generated/\n  product-specs/\n  references/\n  QUALITY_SCORE.md\n  RELIABILITY.md\n  SECURITY.md"
        }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "이 구조는 점진적 공개를 가능하게 합니다. 에이전트는 처음부터 모든 세부 규칙을 읽지 않고, 안정적인 진입점에서 시작해 필요한 문서를 따라가며 컨텍스트를 확장합니다. 문서는 최신성, 링크, 소유권을 자동 검사하고, 오래된 지식은 정리 작업을 통해 업데이트됩니다."
        }
      ]
    },
    {
      "type": "heading",
      "attrs": {
        "level": 2
      },
      "content": [
        {
          "type": "text",
          "text": "5. 운영 하네스 구성요소"
        }
      ]
    },
    {
      "type": "table",
      "content": [
        {
          "type": "tableRow",
          "content": [
            {
              "type": "tableHeader",
              "attrs": {
                "colspan": 1,
                "rowspan": 1,
                "colwidth": null
              },
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "구성요소"
                    }
                  ]
                }
              ]
            },
            {
              "type": "tableHeader",
              "attrs": {
                "colspan": 1,
                "rowspan": 1,
                "colwidth": null
              },
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "목적"
                    }
                  ]
                }
              ]
            },
            {
              "type": "tableHeader",
              "attrs": {
                "colspan": 1,
                "rowspan": 1,
                "colwidth": null
              },
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "에이전트가 얻는 이점"
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "type": "tableRow",
          "content": [
            {
              "type": "tableCell",
              "attrs": {
                "colspan": 1,
                "rowspan": 1,
                "colwidth": null
              },
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "짧은 AGENTS.md"
                    }
                  ]
                }
              ]
            },
            {
              "type": "tableCell",
              "attrs": {
                "colspan": 1,
                "rowspan": 1,
                "colwidth": null
              },
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "리포지터리 탐색 지도 제공"
                    }
                  ]
                }
              ]
            },
            {
              "type": "tableCell",
              "attrs": {
                "colspan": 1,
                "rowspan": 1,
                "colwidth": null
              },
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "필요한 문서와 규칙을 빠르게 찾음"
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "type": "tableRow",
          "content": [
            {
              "type": "tableCell",
              "attrs": {
                "colspan": 1,
                "rowspan": 1,
                "colwidth": null
              },
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "구조적 린터"
                    }
                  ]
                }
              ]
            },
            {
              "type": "tableCell",
              "attrs": {
                "colspan": 1,
                "rowspan": 1,
                "colwidth": null
              },
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "레이어 경계와 명명 규칙 강제"
                    }
                  ]
                }
              ]
            },
            {
              "type": "tableCell",
              "attrs": {
                "colspan": 1,
                "rowspan": 1,
                "colwidth": null
              },
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "아키텍처 드리프트를 즉시 감지"
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "type": "tableRow",
          "content": [
            {
              "type": "tableCell",
              "attrs": {
                "colspan": 1,
                "rowspan": 1,
                "colwidth": null
              },
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "브라우저 검증"
                    }
                  ]
                }
              ]
            },
            {
              "type": "tableCell",
              "attrs": {
                "colspan": 1,
                "rowspan": 1,
                "colwidth": null
              },
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "UI 상태와 사용자 여정 관찰"
                    }
                  ]
                }
              ]
            },
            {
              "type": "tableCell",
              "attrs": {
                "colspan": 1,
                "rowspan": 1,
                "colwidth": null
              },
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "수정 전후 동작을 직접 비교"
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "type": "tableRow",
          "content": [
            {
              "type": "tableCell",
              "attrs": {
                "colspan": 1,
                "rowspan": 1,
                "colwidth": null
              },
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "관측 가능성 스택"
                    }
                  ]
                }
              ]
            },
            {
              "type": "tableCell",
              "attrs": {
                "colspan": 1,
                "rowspan": 1,
                "colwidth": null
              },
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "로그, 메트릭, 트레이스 질의"
                    }
                  ]
                }
              ]
            },
            {
              "type": "tableCell",
              "attrs": {
                "colspan": 1,
                "rowspan": 1,
                "colwidth": null
              },
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "성능과 장애 원인을 실행 중에 추론"
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "type": "tableRow",
          "content": [
            {
              "type": "tableCell",
              "attrs": {
                "colspan": 1,
                "rowspan": 1,
                "colwidth": null
              },
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "실행 계획"
                    }
                  ]
                }
              ]
            },
            {
              "type": "tableCell",
              "attrs": {
                "colspan": 1,
                "rowspan": 1,
                "colwidth": null
              },
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "의도, 진행 상황, 결정 기록 관리"
                    }
                  ]
                }
              ]
            },
            {
              "type": "tableCell",
              "attrs": {
                "colspan": 1,
                "rowspan": 1,
                "colwidth": null
              },
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "긴 작업을 중단 없이 이어받음"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "type": "heading",
      "attrs": {
        "level": 2
      },
      "content": [
        {
          "type": "text",
          "text": "6. 아키텍처와 취향을 코드로 강제하기"
        }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "문서만으로는 코드베이스 일관성을 유지하기 어렵습니다. 그래서 반복적으로 중요한 규칙은 린터, 구조 테스트, 타입 경계, 생성 스크립트 같은 기계적 장치로 승격합니다. 원문에서는 고정된 레이어와 제한된 의존성 방향을 둬서 에이전트가 빠르게 작업해도 시스템의 기본 형태가 무너지지 않게 하는 방식을 소개합니다."
        }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "예를 들어 도메인 코드는 "
        },
        {
          "type": "text",
          "text": "Types → Config → Repo → Service → Runtime → UI",
          "marks": [
            {
              "type": "code"
            }
          ]
        },
        {
          "type": "text",
          "text": " 같은 예측 가능한 흐름을 따르고, 인증이나 텔레메트리 같은 횡단 관심사는 명시적인 provider 경계로만 들어오게 할 수 있습니다."
        }
      ]
    },
    {
      "type": "horizontalRule"
    },
    {
      "type": "imageBlock",
      "attrs": {
        "src": "data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 width=%22960%22 height=%22540%22 viewBox=%220 0 960 540%22%3E%3Crect width=%22960%22 height=%22540%22 fill=%22%23f8fafc%22/%3E%3Crect x=%2272%22 y=%2272%22 width=%22816%22 height=%22396%22 rx=%2224%22 fill=%22%23dcfce7%22/%3E%3Cpath d=%22M152 364h656%22 stroke=%22%230f172a%22 stroke-width=%2210%22 stroke-linecap=%22round%22 opacity=%22.75%22/%3E%3Cpath d=%22M220 364V212h172v152M488 364V172h164v192M720 364V248h88%22 fill=%22none%22 stroke=%22%232563eb%22 stroke-width=%2214%22 stroke-linecap=%22round%22 stroke-linejoin=%22round%22/%3E%3Ccircle cx=%22392%22 cy=%22212%22 r=%2228%22 fill=%22%23f59e0b%22/%3E%3Ccircle cx=%22652%22 cy=%22172%22 r=%2228%22 fill=%22%23f59e0b%22/%3E%3Ccircle cx=%22808%22 cy=%22248%22 r=%2228%22 fill=%22%23f59e0b%22/%3E%3Ctext x=%22144%22 y=%22124%22 font-family=%22Arial%2C sans-serif%22 font-size=%2244%22 font-weight=%22700%22 fill=%22%230f172a%22%3EAgent Harness%3C/text%3E%3Ctext x=%22144%22 y=%22438%22 font-family=%22Arial%2C sans-serif%22 font-size=%2228%22 fill=%22%23334155%22%3Etools %E2%80%A2 feedback loops %E2%80%A2 repository knowledge%3C/text%3E%3C/svg%3E",
        "alt": "Agent harness overview diagram",
        "align": "center",
        "width": "86%"
      },
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "그림 1. 에이전트 운영 하네스의 개념도. 도구, 피드백 루프, 리포지터리 지식이 연결될수록 Codex가 스스로 검증할 수 있는 범위가 넓어집니다."
            }
          ]
        }
      ]
    },
    {
      "type": "heading",
      "attrs": {
        "level": 2
      },
      "content": [
        {
          "type": "text",
          "text": "7. 처리량이 병합 철학을 바꾼다"
        }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "에이전트의 처리량이 높아지면 기존의 병합 문화도 달라집니다. PR은 더 작고 짧게 유지되며, 실패 비용이 낮은 문제는 긴 대기보다 후속 실행으로 빠르게 고치는 편이 더 유리할 수 있습니다. 중요한 것은 무작정 많이 병합하는 것이 아니라, 검증 루프와 복구 루프가 충분히 짧아졌는지 확인하는 것입니다."
        }
      ]
    },
    {
      "type": "bulletList",
      "content": [
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "사람의 주의력은 가장 희소한 자원으로 취급한다."
                }
              ]
            }
          ]
        },
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "에이전트 리뷰와 자동 검증으로 반복 작업을 흡수한다."
                }
              ]
            }
          ]
        },
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "사람이 판단해야 하는 변경은 명확히 에스컬레이션한다."
                }
              ]
            }
          ]
        },
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "작은 PR과 빠른 복구를 통해 대기 시간을 줄인다."
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "type": "heading",
      "attrs": {
        "level": 2
      },
      "content": [
        {
          "type": "text",
          "text": "8. 엔트로피와 가비지 컬렉션"
        }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "에이전트가 기존 패턴을 잘 복제한다는 점은 장점이지만, 좋지 않은 패턴도 같이 증폭될 수 있습니다. 따라서 정리 작업을 이벤트가 아니라 지속적인 백그라운드 프로세스로 봐야 합니다. 품질 등급을 갱신하고, 오래된 문서를 고치고, 반복되는 문제를 공유 유틸리티나 린트 규칙으로 끌어올리는 작업이 필요합니다."
        }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "이 문서의 결론은 코드 생성 자체보다 스캐폴딩, 추상화, 피드백 루프가 더 중요해지고 있다는 것입니다. 에이전트가 복잡하고 안정적인 소프트웨어를 다루려면 사람이 목표를 명확히 하고, 시스템이 그 목표를 검증할 수 있어야 합니다."
        }
      ]
    },
    {
      "type": "fileBlock",
      "attrs": {
        "url": "/mock-files/codex-agent-harness-review.pdf",
        "fileName": "codex-agent-harness-review.pdf",
        "fileSize": 624880,
        "fileType": "application/pdf"
      }
    },
    {
      "type": "linkBlock",
      "attrs": {
        "url": "https://openai.com/ko-KR/index/harness-engineering/",
        "title": "하네스 엔지니어링: 에이전트 우선 세계에서 Codex 활용하기",
        "description": "Codex 에이전트가 제품 개발, 검증, 리뷰, 정리 루프를 수행할 수 있도록 환경을 설계한 OpenAI 엔지니어링 사례.",
        "image": "data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 width=%22960%22 height=%22540%22 viewBox=%220 0 960 540%22%3E%3Crect width=%22960%22 height=%22540%22 fill=%22%23f8fafc%22/%3E%3Crect x=%2272%22 y=%2272%22 width=%22816%22 height=%22396%22 rx=%2224%22 fill=%22%23dcfce7%22/%3E%3Cpath d=%22M152 364h656%22 stroke=%22%230f172a%22 stroke-width=%2210%22 stroke-linecap=%22round%22 opacity=%22.75%22/%3E%3Cpath d=%22M220 364V212h172v152M488 364V172h164v192M720 364V248h88%22 fill=%22none%22 stroke=%22%232563eb%22 stroke-width=%2214%22 stroke-linecap=%22round%22 stroke-linejoin=%22round%22/%3E%3Ccircle cx=%22392%22 cy=%22212%22 r=%2228%22 fill=%22%23f59e0b%22/%3E%3Ccircle cx=%22652%22 cy=%22172%22 r=%2228%22 fill=%22%23f59e0b%22/%3E%3Ccircle cx=%22808%22 cy=%22248%22 r=%2228%22 fill=%22%23f59e0b%22/%3E%3Ctext x=%22144%22 y=%22124%22 font-family=%22Arial%2C sans-serif%22 font-size=%2244%22 font-weight=%22700%22 fill=%22%230f172a%22%3EAgent Harness%3C/text%3E%3Ctext x=%22144%22 y=%22438%22 font-family=%22Arial%2C sans-serif%22 font-size=%2228%22 fill=%22%23334155%22%3Etools %E2%80%A2 feedback loops %E2%80%A2 repository knowledge%3C/text%3E%3C/svg%3E"
      }
    },
    {
      "type": "imageUpload"
    }
  ]
}