Codex App을 기술 작업대로 만들기──화면, 파일, thread, review 사용법 제7회

Codex App은 단순한 「채팅으로 코드를 작성하게 하는 화면」이 아닙니다.

잘 활용하면, 기술 작업의 작업대가 됩니다.

리포지토리(Repository)를 연결한다.

thread를 나눈다.

파일을 읽게 한다.

화면을 보여준다.

에러를 설명하게 한다.

수정안을 만들게 한다.

리뷰(Review)하게 한다.

다음에 남길 것을 정리하게 한다.

CLI는 수중에 두고 빠르게 작업하기에는 강력합니다.

하지만, Codex App에는 또 다른 강점이 있습니다.

화면으로 작업을 볼 수 있다.

thread와 project로 문맥(Context)을 나눌 수 있다.

여러 작업을 나란히 두고 관리하기 쉽다.

스크린샷이나 앱 화면을 전달하기 쉽다.

기술자가 아닌 사람도 작업의 입구로 들어오기 쉽다.

제6회에서는 기존 리포지토리 조사와 장애 조사에서 agent를 사용하는 방법을 썼습니다.

이번에는 Codex App입니다.

특히 비엔지니어(Non-engineer)나 주변 직종의 사람들도 이해할 수 있도록, 작업의 유형으로서 작성합니다.

ChatGPT의 연장선으로 보면, Codex App은 대화 화면으로 보입니다.

하지만 개발에서 사용한다면 대화가 아니라 작업장으로 보는 것이 좋습니다.

대화라면, 하나의 thread에 무엇이든 던지고 싶어집니다.

이 에러 좀 봐줘.
하는 김에 UI도 고쳐줘.
그리고 README도 업데이트해줘.

이렇게 하면 문맥이 섞입니다.

작업장으로 본다면, thread를 나눕니다.

Thread A: 상품 검색 장애 조사
Thread B: 상품 검색 UI 수정
Thread C: PR review
...

1 thread 1 목적.

이것만으로도 상당히 사용하기 편해집니다.

Codex App에서는 project를 만들어 폴더나 리포지토리에 접속합니다.

project는 단순한 저장 공간이 아닙니다.

agent에게 보여줄 작업 범위입니다.

그러므로 처음부터 거대한 홈 디렉토리(Home directory)를 선택하지 않는 것이 좋습니다.

좋은 project를 만드는 방법입니다.

Project:
- 대상 리포지토리 단위
- 또는, 작업용으로 나눈 작은 폴더
...

비엔지니어가 사용하는 경우도 마찬가지입니다.

예를 들어, 영업 자료를 정리한다면 프로젝트용 폴더를 만듭니다.

customer-brief/
source-notes/
slides/
...

그 부분만을 Codex App에 보여줍니다.

데스크톱 전체를 보여주지 않습니다.

이는 보안 때문만은 아닙니다.

agent가 길을 잃지 않기 위해서이기도 합니다.

thread는 태스크(Task)의 단위입니다.

하나의 thread로 하나의 목적을 만듭니다.

나쁜 사용법입니다.

이 프로젝트 전체를 좋게 만들어줘.

좋은 사용법입니다.

이 thread에서는 상품 검색의 장애 조사만 합니다.
아직 수정하지 마세요.
출력:
...

thread의 처음에 목적과 금지 사항을 적습니다.

이것만으로도 작업이 긴밀해집니다.

새로운 project를 만들었다면, 곧바로 구현하지 않습니다.

첫 번째 thread는 project 조사로 합니다.

이 project를 read-only로 조사해 주세요.
아직 파일은 변경하지 마세요.
출력:
...

이 thread는 이후 작업의 지도가 됩니다.

출력이 좋다면, INDEX.md나 AGENTS.md로 되돌립니다.

이 조사 결과로부터, 다음 agent가 처음에 읽기 위한 INDEX.md 안을 만들어 주세요.

이렇게 하면 Codex App의 첫 대화가 다음 작업을 편하게 만듭니다.

화면을 보여줄 수 있는 환경에서는 Appshots나 스크린샷이 상당히 효과적입니다.

특히 말로 설명하기 어려운 것들입니다.

• UI가 깨져 있음
• 버튼이 잘려 있음
• 표의 열 너비가 이상함
• 에러 화면이 떠 있음
• 관리 화면의 조작법을 모름
• PPT나 자료의 레이아웃이 이상함
• 브라우저상의 폼(Form)이 의도대로 작동하지 않음

이럴 때는 길게 설명하는 것보다 화면을 전달하는 편이 빠릅니다.

단, 화면을 전달할 때도 경계를 적습니다.

이 화면을 보고, UI 깨짐의 원인 후보를 내주세요.
아직 파일은 변경하지 마세요.
봐주었으면 하는 것:
...

화면을 전달하면 agent는 강력해집니다.

그렇기에 무엇을 볼지도 적습니다.

화면 공유의 가치는 설명을 편하게 하는 것만이 아닙니다.

증거로 사용할 수 있다는 점입니다.

예를 들어, 사용자로부터 "검색 화면이 고장 났어요"라는 말을 들었다고 가정해 봅시다.

사람이 말로 설명하면 모호해집니다.

검색창 근처가 이상해요.

화면을 전달하면 구체화할 수 있습니다.

이 화면으로부터 UI상의 문제를 사실과 추측으로 나누어 주세요.
Facts:
- 화면상에서 보이는 것
...

agent에게 "화면에서 사실과 추측을 나누도록" 요청하면 조사에 들어가기 쉬워집니다.

Codex App의 큰 의미는 코드를 쓸 줄 아는 사람만을 위한 것이 아니라는 점입니다.

비엔지니어(Non-engineer)가 갑자기 코드를 수정할 필요는 없습니다.

하지만 다음 작업에는 사용할 수 있습니다.

• 에러 화면을 설명하게 하기
• 관리자 화면의 조작 절차를 정리하게 하기
• CSV 전처리 안을 만들기
• 사양서의 불명확한 점을 찾아내기
• 개발자에게 전달할 버그 보고서 만들기
• PR 설명을 읽기 쉽게 만들기
• 테스트 관점 만들기
• FAQ나 절차서의 초안 만들기

여기서 중요한 것은 Codex App에게 "개발을 전부 시키는 것"이 아닙니다.

기술자에게 전달할 재료를 정돈하는 것입니다.

비엔지니어의 의뢰 예시입니다.

이 에러 화면과 조작 메모를 바탕으로, 개발자에게 전달할 버그 보고서를 작성해 주세요.
포함할 내용:
- 무엇을 하려고 했는지
...

이것은 상당히 실용적입니다.

개발자는 "무슨 일이 일어났는지" 다시 되묻는 시간을 줄일 수 있습니다.

비엔지니어도 기술적인 보고를 만들기 쉬워집니다.

Codex CLI와 Codex App 중 어느 쪽이 더 우월하다는 이야기가 아닙니다.

적합한 상황이 다릅니다.

CLI가 적합한 경우:

• 수동으로 빠르게 파일을 읽히기
• 작은 수정을 진행하기
• 테스트를 돌리면서 수정하기
• terminal의 흐름에 태우기
• 혼자서 집중하여 작업하기

App이 적합한 경우:

• project / thread를 나누어 관리하기
• 여러 작업을 나열하기
• 화면이나 스크린샷을 전달하기
• 비엔지니어와 작업 공유하기
• 긴 조사나 리뷰를 남기기
• 진행 중인 작업을 다시 보기

使い分け(용도 구분)는 단순합니다.

수동으로 빠르게 고친다면 CLI.
작업을 보여주고, 남기고, 나눈다면 App.

frontend 작업에서는 화면이 중요합니다.

코드만 봐서는 알 수 없는 것들이 있습니다.

• hover 시 레이아웃이 깨짐
• 모바일에서만 겹침
• 문구가 버튼 밖으로 나감
• empty state가 보기 불편함
• loading 중에 layout shift 발생
• table의 열이 너무 좁음

Codex App에서는 화면을 전달하며 이렇게 요청합니다.

이 화면을 보고 frontend review를 해주세요.
확인할 것:
- text overflow
...

여기서도 갑자기 수정하지 않는 것이 좋습니다.

먼저 review.

그다음 최소 수정.

마지막으로 재체크.

이 순서가 안정적입니다.

상품 검색 UI 깨짐을 고치는 경우, thread를 다음과 같이 나눕니다.

Thread 1: 화면 확인
- Appshot / screenshot을 보여줌
- 사실과 원인 후보를 나눔
...

하나의 thread에 전부 몰아넣지 마세요.

이것이 중요합니다.

thread를 나누면 사람도 다시 보기 쉽습니다.

"어디서 판단했는지"가 남습니다.

첫 번째 project 조사:

이 project를 read-only로 조사해 주세요.
아직 변경하지 마세요.
출력:
...

화면 확인:

이 화면을 보고 문제를 사실과 추측으로 나누어 주세요.
아직 수정하지 마세요.
출력:
...

비엔지니어용 버그 보고:

이 화면과 메모를 바탕으로 개발자에게 전달할 버그 보고서를 작성해 주세요.
포함할 내용:
- 조작 절차
...

PR review:

이 차분(diff)을 review해 주세요.
확인할 것:
- 사양에서 벗어나지 않았는지
...

Compound:

이번 작업에서 다음으로 되돌려야 할 것을 정리해 주세요.
나눌 것:
- AGENTS.md에 넣을 규칙
...

Codex App이 편리하더라도 무엇이든 다 넣는 것은 좋지 않습니다.

피해야 할 사용법입니다.

• 하나의 thread에 모든 것을 담기
• project와 관계없는 폴더까지 보여주기
• secret이나 개인 메모가 포함된 폴더를 선택하기
• 화면을 전달하며 "전부 고쳐줘"라고 부탁하기
• 변경 범위를 작성하지 않기
• 화면상의 정보를 그대로 사실로 취급하기
• review 없이 외부 서비스에 반영하기

App은 작업대입니다.

작업대에는 필요한 것만 올려둡니다.

Codex App은 채팅 화면이 아니라 작업대로 사용할 때 강력합니다.

project는 작업 범위.

thread는 작업 단위.

Appshots나 스크린샷은 설명을 줄이기 위한 재료.

화면은 증거로서 취급.

CLI는 수중에 있는 빠른 작업.

App은 보여주고, 남기고, 나누는 작업.

비엔지니어에게도 Codex App은 단순히 "코드를 쓰는 도구"만이 아닙니다.

에러를 설명합니다.

버그 보고를 정리합니다.

사양의 불분명한 점을 도출합니다.

개발자에게 전달할 재료를 만듭니다.

이 점이 매우 중요합니다.

다음 회차는 지금까지의 흐름을 그대로 복사해서 사용할 수 있는 템플릿 모음으로 준비하겠습니다.