이 글의 기준은 Codex App / Codex Desktop이다. 터미널에서 codex를 직접 실행하는 Codex CLI 기준이 아니다.
Codex Desktop은 프로젝트 폴더를 열고, 여러 thread와 worktree를 병렬로 굴리는 데스크톱 작업 공간이다. 그래서 도구를 붙일 때도 CLI 기준으로 생각하면 헷갈린다.
내가 만들려는 구조는 이렇다.
Codex Desktop
→ 여러 thread/worktree로 작업한다.
Codesight
→ 프로젝트 구조를 미리 스캔해서 AI가 읽을 지도를 만든다.
agentmemory
→ thread와 세션 사이의 작업 기억을 이어준다.
OmO / LazyCodex
→ Codex lifecycle에 보조 hook/plugin을 붙인다.
왜 이 셋을 붙이는가
Codex Desktop을 쓰면 thread를 여러 개 만들 수 있다. 이건 강점이다. 하지만 thread가 많아지면 같은 문제가 반복된다.
프로젝트 구조를 매번 다시 읽는다.
이전 thread에서 실패한 접근을 다른 thread가 다시 시도한다.
작업 종료 후 다음 thread로 넘길 맥락이 사라진다.
어떤 문서가 진짜 기준인지 헷갈린다.
그래서 역할을 나눈다.
| 도구 | 무엇을 해주는가 | 왜 필요한가 |
| Codesight | 코드베이스 지도를 만든다 | 새 thread가 프로젝트 구조를 빨리 이해하게 한다 |
| agentmemory | 작업 기억을 저장하고 검색한다 | 이전 thread의 결정·실패·handoff를 이어받게 한다 |
| OmO | Codex hook/plugin으로 실행 보조를 붙인다 | rules, checker, LSP, ultrawork, continuation 같은 보조 기능을 쓴다 |
Codex Desktop 기준 작업 흐름
Codex Desktop에서는 보통 이렇게 작업한다.
1. 앱에서 프로젝트 폴더를 연다.
2. thread를 만든다.
3. Codex가 별도 worktree에서 작업한다.
4. 변경사항을 리뷰한다.
5. 필요하면 반영하거나 버린다.
여기에 세 도구를 붙이면 흐름은 이렇게 바뀐다.
1. 프로젝트 루트에 AGENTS.md와 docs/**를 둔다.
2. Codesight로 .codesight/wiki를 만든다.
3. agentmemory 서버를 띄우고 MCP를 연결한다.
4. 필요하면 agentmemory hook을 연결한다.
5. OmO/LazyCodex를 설치한다.
6. Codex Desktop thread 시작 시 AGENTS.md, Codesight, memory를 읽게 한다.
7. 작업 종료 전 handoff를 남긴다.
CLI 명령을 아예 안 쓰는 것은 아니다. Codex Desktop을 쓰더라도 설치, 갱신, 서버 실행은 터미널에서 한다.
Codesight
무엇을 해주는가
Codesight는 코드베이스 지도를 만든다. Codex Desktop에서 새 thread를 만들면 thread는 프로젝트를 다시 이해해야 한다.
백엔드는 어디인가?
프론트엔드는 어디인가?
테스트는 어디인가?
도메인 문서는 어디인가?
어떤 파일을 먼저 읽어야 하는가?
Codesight는 이 탐색을 미리 해둔다.
프로젝트 스캔
→ .codesight/wiki 생성
→ Codex Desktop thread가 구조 파악용으로 읽음
즉, Codesight는 코드를 고치는 도구가 아니다.
Codesight = AI가 읽는 프로젝트 지도어떻게 적용하는가
프로젝트 루트에서 실행한다.
npx codesight --wiki
생성 결과를 확인한다.
find .codesight -maxdepth 3 -type f | sort
AGENTS.md에는 짧게 적는다.
## Codesight
- .codesight/wiki가 있으면 구조 파악용으로 읽어라.
- Codesight 결과물은 Source of Truth가 아니다.
- 정책 판단은 AGENTS.md와 docs/**에서 다시 확인해라.코드 변경 시 어떻게 하는가
Codesight는 생성 산출물이다. 코드가 바뀌면 지도도 낡는다. 하지만 모든 수정마다 돌릴 필요는 없다.
작은 버그 수정
→ 갱신 안 함
문서 구조 변경
→ npx codesight --wiki
패키지 구조 변경
→ npx codesight --wiki
큰 리팩토링 전
→ npx codesight --wiki
큰 리팩토링 중 구조가 계속 바뀜
→ npx codesight --watch
커밋마다 자동 갱신
→ 기본값으로 쓰지 않음
--hook은 조심한다.
npx codesight --hook
커밋마다 Codesight 생성 파일이 바뀌면 커밋 범위가 지저분해질 수 있다. 개인 프로젝트에서는 처음부터 hook을 기본값으로 둘 필요 없다.
Codex Desktop worktree 주의점
Codex Desktop은 thread별 worktree를 만들 수 있다. 그래서 Codesight를 실행할 때는 현재 갱신하려는 worktree 경로에서 실행해야 한다.
cd <codex-desktop-worktree-path>
npx codesight --wiki
원본 프로젝트 루트에서 만든. codesight/wiki와 Codex Desktop thread의 worktree 안 파일 상태가 다를 수 있다.
이 차이를 모르면 낡은 지도를 보고 작업하게 된다.
agentmemory
무엇을 해주는가
agentmemory는 작업 기억을 저장한다. Codex Desktop에서는 thread가 여러 개 생긴다. 그러면 이런 문제가 생긴다.
A thread에서 실패한 접근을 B thread가 다시 시도한다.
어제 thread에서 남긴 다음 작업을 오늘 thread가 모른다.
사용자가 금지한 방향을 다른 thread가 다시 제안한다.
agentmemory는 이런 기억을 저장하고 다시 꺼내게 한다.
저장할 것은 이 정도다.
완료한 작업
실패한 접근
다음 작업
주의사항
handoff
정책 문서 위치
저장하면 안 되는 것도 있다.
긴 로그 전문
비밀값
검증되지 않은 추측
docs에 없는 정책 단정
이미 docs에 있는 내용을 그대로 복붙한 장문
정책은 docs에 두고, memory에는 작업 기억과 정책 문서 위치를 남긴다.
어떻게 실행하는가
https://github.com/rohitg00/agentmemory 에서 확인한다. 나는 설치 방식을 선호하고 작업 중에는 터미널에서 agentmemory 서버를 항상 실행한다.
Codex Desktop에 어떻게 붙이는가
Codex Desktop에서 생각할 통로는 두 개다.
MCP
→ Codex Desktop이 memory를 검색하고 읽는 통로
hook
→ 작업 이벤트를 memory에 자동 기록하는 통로
처음에는 MCP부터 붙인다. 자동 기록보다 검색이 되는지 먼저 확인하는 게 낫다.
MCP 등록은 Codex Desktop 설정에서 하거나, 환경에 따라 다음 명령으로 Codex 설정에 추가한다.
codex mcp add agentmemory -- npx -y @agentmemory/mcp
AGENTS.md에도 추가한다.
## agentmemory
- agentmemory MCP가 연결되어 있다면 현재 프로젝트의 최근 memory를 검색해라.
- 검색 결과가 없으면 없다고 말해라.
- memory 내용이 AGENTS.md 또는 docs/**와 충돌하면 AGENTS.md와 docs/**를 우선한다.
hook까지 쓰려면 CodexApp의 훅 설정을 하면 된다.
아래 명령어는 Codex Desktop에서 plugin-local hook이 기대대로 동작하지 않을 때 global hook으로 우회 연결하는 용도다. 때문에 훅이 중복 등록되어 중복 호출될 수 있다. 잘 확인하고 실행하자
agentmemory connect codex --with-hooks
내 적용 순서는 이렇다.
1. agentmemory 서버 실행
2. MCP 연결
3. Codex Desktop thread에서 memory 검색 테스트
4. handoff를 수동으로 기록하도록 지시
5. 필요하면 hook 연결
6. hook이 실제로 기록하는지 확인
OmO / LazyCodex
무엇을 해주는가
OmO는 Codex 또는 OpenCode의 실행 흐름을 보조하는 harness다. Codex 쪽에서는 LazyCodex Light edition으로 붙는다.
설치하면 Codex plugin cache 아래에 OmO plugin이 들어가고, hooks/hooks.json을 통해 Codex lifecycle에 붙는다.
보통 이런 경로를 확인할 수 있다.
~/.codex/plugins/cache/sisyphuslabs/omo/<version>/hooks/hooks.json
Codex Desktop 기준에서 OmO에 기대하는 역할은 이렇다.
rules 보조
comment checker 보조
LSP 기반 피드백 보조
ultrawork / ulw 흐름 보조
작업 continuation 보조
telemetry
git-bash 보조
즉, OmO를 이렇게 보면 안 된다.
OmO = SparkShell
더 정확히는 이렇다.
OmO = Codex lifecycle 보조 hook/plugin 묶음어떻게 설치하는가
Codex용 LazyCodex를 설치한다.
npx lazycodex-ai install
자동화 옵션까지 적용하려면 다음을 쓴다.
npx lazycodex-ai install --no-tui --codex-autonomous
설정이 들어갔는지 확인한다.
grep -n "omo" ~/.codex/config.toml
grep -n "plugin" ~/.codex/config.toml
ls ~/.codex
plugin cache를 확인한다.
find ~/.codex/plugins/cache/sisyphuslabs/omo -path '*/hooks/hooks.json'
omo 명령이 안 잡히면 PATH를 추가한다.
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
주의할 점도 있다.
Codex용
→ npx lazycodex-ai install
OpenCode용
→ bunx oh-my-openagent install
npx omo / bunx omo
→ 쓰지 않는다. 다른 패키지로 해석될 수 있다.OmO를 실제로 어떻게 쓰는가
Codex Desktop에서 OmO는 별도 명령으로 매번 실행하는 도구가 아니다.
틀린 이해:
작업할 때마다 OmO 명령을 직접 실행한다.
맞는 이해:
OmO plugin/hook을 설치하고 승인한다.
Codex lifecycle에 붙은 보조 기능이 필요한 이벤트에서 개입하게 둔다.
ulw 또는 ultrawork 키워드를 써서 깊은 작업 모드를 유도하는 쪽이 현실적이다.
하지만 나는 훅으로 등록해서 사용중이다. thread가 작업하는 동안 발생하는 로그를 보면 에이전트가 필요한 명령을 판단해서 사용하는걸 볼 수 있다.
ulw: 이 작업을 끝까지 진행해라.
먼저 계획을 세우고, 작은 단위로 구현하고, 테스트 결과까지 확인해라.
중간에 멈추지 말고 실패 원인을 보고해라.
또는
ultrawork 모드로 진행해라.
작업 계획, 구현, 검증, 남은 리스크를 순서대로 보고해라.
AGENTS.md
도구를 설치해도 Codex Desktop이 알아서 잘 쓰지는 않는다. 명시적으로 사용방법을 가이드한다.
짧게 쓴다고 쓴건데... 너무 길다
# 저장소 작업 규칙
이 파일은 AI coding agent가 이 저장소에서 작업할 때 따르는 공통 규칙이다.
특정 도구나 실행 환경에 종속되지 않는다.
Codex Desktop, Codex CLI, Cursor, Claude Code, OpenCode 등 어떤 에이전트가 실행되더라도 이 파일을 먼저 따른다.
---
## 문서와 도구의 우선순위
- **AGENTS.md**: 모든 에이전트가 항상 따르는 공통 작업 규칙.
- **docs/**: Source of Truth. 오래가는 제품·도메인·아키텍처 정책을 둔다.
- **Codesight**: 코드베이스 지도와 탐색 보조 도구. 생성 산출물이며 Source of Truth가 아니다.
- **agentmemory**: 최근 결정, 금지사항, 반복 회귀 원인, handoff, 세션 요약을 저장·조회하는 작업 메모리. Source of Truth가 아니다.
- **OmO / LazyCodex**: Codex lifecycle에 보조 hook/plugin을 붙이는 실행 보조 도구. Source of Truth가 아니다.
에이전트는 자신이 어떤 실행 환경에서 동작하는지 확실히 알 수 없으므로, 이 파일에서는 실행 환경별 역할을 전제하지 않는다.
---
## 기본 원칙
- Source of Truth는 `AGENTS.md`와 `docs/**`이다.
- Codesight, agentmemory, OmO 결과는 모두 보조 정보다.
- 보조 정보가 Source of Truth와 충돌하면 Source of Truth를 우선한다.
- 작업 범위는 사용자의 요청 범위로 제한한다.
- 오래가는 제품·도메인·아키텍처 정책은 docs에 둔다.
- 정책 변경이 필요한 작업은 docs를 먼저 수정한다.
- 단순 버그 수정에서 정책이 바뀌지 않으면 docs를 건드리지 않는다.
- 테스트 통과만으로 UI 완료를 선언하지 않는다.
- 실제 화면을 확인하지 못했으면 수동 확인 미완료라고 보고한다.
- 모르는 것을 추측해서 확정하지 않는다.
- 근거가 부족하면 부족하다고 보고하고, 확인 가능한 근거를 우선한다.
---
## 기본 작업 순서
작업자는 항상 다음 순서를 따른다.
1. `AGENTS.md`
2. 작업이 단순 문구 수정이 아니라면 agentmemory에서 관련 memory recall
3. `docs/README.md`가 있으면 읽는다
4. `docs/project/status.md`가 있으면 읽는다
5. `docs/project/roadmap.md`가 있으면 읽는다
6. `.codesight/wiki/index.md`가 있으면 읽는다
7. 현재 작업 entrypoint를 찾는다
8. `.codesight/wiki/*` 중 현재 작업과 직접 관련된 article 1~2개를 읽는다
9. 관련 `docs/architecture/*`가 있으면 읽는다
10. 필요 시 `docs/reference/*`를 읽는다
11. 필요한 원본 코드 파일을 읽는다
위 문서나 디렉터리가 없으면 없는 것으로 보고하고, 존재하는 문서를 기준으로 진행한다.
장기 결정 배경은 가능하면 `docs/project/decision-log.md`에 둔다.
구현 근거는 현재 `docs/**`와 실제 코드를 우선한다.
---
## 문서 유지·삭제 정책
문서는 개발 판단과 구현에 직접 도움이 될 때만 유지한다.
삭제·이동 판단 기준은 다음과 같다.
- 현재 구현·정책·운영 판단에 쓰이지 않는 문서는 유지하지 않는다.
- Source of Truth를 반복하는 중복 문서는 하나로 합친다.
- 과거 결정 배경은 필요하면 decision log에 남기고, 긴 임시 문서는 삭제 또는 archive 처리한다.
- generated output은 재생성 가능한 산출물로 보고 수동 보존 가치를 두지 않는다.
- 삭제가 코드 탐색이나 정책 판단을 더 어렵게 만들면 삭제하지 않는다.
- 문서 삭제나 이동은 작업 보고에 명시한다.
---
## Codesight 사용 정책
Codesight는 코드 탐색 비용과 토큰 사용량을 줄이기 위한 보조 도구다.
Codesight output은 Source of Truth가 아니며, docs 또는 실제 코드와 충돌하면 docs와 실제 코드를 우선한다.
### 기본 원칙
- 세션 시작 시 `.codesight/CODESIGHT.md` 전체를 읽지 않는다.
- 먼저 `.codesight/wiki/index.md`만 읽고 현재 작업에 필요한 article을 고른다.
- 좁은 작업은 관련 wiki article 1개와 entrypoint 코드만 읽고 시작한다.
- 넓은 리팩토링, 영향도 분석, 구조 파악이 필요할 때만 Codesight graph/raw output을 추가로 참고한다.
- Codesight output이 stale로 보이면 stale 가능성을 보고하고, 실제 코드와 Source of Truth 문서를 기준으로 판단한다.
- Codesight 결과는 위치 탐색에 사용하고, 정책 판단에는 사용하지 않는다.
### 권장 사용 방식
- **Backend/API 작업**: `index.md` → 관련 route/service/database article → 관련 docs
- **Frontend/UI 작업**: `index.md` → 관련 page/component/state article → 관련 docs
- **DB/Migration 작업**: `index.md` → database article → 관련 migration과 roadmap
- **아키텍처 변경**: `index.md` → overview article → 관련 architecture docs
- **외부 연동 작업**: Codesight보다 먼저 `docs/reference/**`와 provider별 reference 문서를 확인한다.
### 금지
- 매 작업마다 `.codesight/CODESIGHT.md` 전체를 읽지 않는다.
- `.codesight/wiki/*`를 Source of Truth처럼 취급하지 않는다.
- `.codesight/` 아래에 사람이 작성한 수동 topic map을 만들거나 유지하지 않는다.
- generated Codesight raw output을 agentmemory에 저장하지 않는다.
- Codesight stale 가능성을 무시하고 구현 판단을 확정하지 않는다.
---
## agentmemory 사용 정책
agentmemory는 최근 결정, 금지사항, 반복 회귀 원인, handoff, 세션 요약을 저장·조회하는 작업 메모리다.
agentmemory는 Source of Truth가 아니다.
agentmemory 내용이 `AGENTS.md` 또는 `docs/**`와 충돌하면 반드시 Source of Truth를 우선한다.
agentmemory는 다음 방식으로 사용할 수 있다.
- MCP를 통한 수동 recall/remember
- 세션 종료 시 자동 세션 요약
- hook 기반 자동 기록
- hook 기반 자동 요약
- 다음 세션 시작 시 최근 handoff/context recall
자동 기록과 자동 요약은 전체 로그를 무제한 저장하는 용도가 아니다.
저장 대상은 다음 작업에 반복적으로 영향을 줄 짧은 맥락으로 제한한다.
### 작업 시작 시
단순 문구 수정이 아닌 작업은 시작 시 agentmemory를 recall한다.
다음 중 하나에 해당하면 작업 시작 시 반드시 agentmemory를 recall한다.
- 넓은 코드 변경
- 리팩토링
- 도메인 정책 변경
- 데이터 정합성 관련 변경
- 인증, 권한, 결제, 금융, 보안, 외부 연동 관련 변경
- 외부 provider ingest 또는 adapter 관련 변경
- 이전 회귀 가능성이 있는 버그 수정
- 사용자가 "전에 정한 것", "기존 정책", "최근 결정"을 언급한 작업
- 다음 작업자에게 이어질 가능성이 있는 작업
기본 recall 대상:
- PROJECT HOT
- PROJECT FORBIDDEN
- PROJECT HANDOFF
- 최근 세션 요약
필요 시 추가 recall 대상:
- PROJECT STALE
- 현재 작업 키워드
- 관련 도메인 키워드
recall한 memory는 최근 작업 맥락으로만 사용한다.
memory가 현재 docs와 충돌하거나 오래된 것으로 보이면 작업을 멈추고 stale 가능성을 보고한다.
agentmemory가 비활성화되어 있거나 recall에 실패해도 작업은 `AGENTS.md`와 docs 기준으로 진행하되, 보고서에 recall 실패를 명시한다.
### 작업 종료 시
작업 종료 시 agentmemory에 짧은 요약을 남길 수 있다.
특히 다음 중 하나가 생기면 remember한다.
- 새로 확정된 프로젝트 정책
- 반복 회귀 원인
- 금지된 구현 방식
- 다음 작업자가 알아야 할 짧은 handoff
- 향후 에이전트 작업에 반복적으로 영향을 줄 결정
- 현재 docs 반영 전까지 임시로 기억해야 할 주의사항
- 긴 작업을 중단하거나 다음 세션으로 넘겨야 하는 경우의 현재 상태
정책이 바뀌지 않은 일반 구현 작업이라도, 다음 세션에서 바로 이어서 작업할 가능성이 있으면 짧은 HANDOFF를 남길 수 있다.
### 자동 세션 요약 / hook 사용
agentmemory hook 기반 자동 기록·자동 요약은 사용할 수 있다.
다만 hook은 다음 원칙을 따른다.
- 전체 세션 로그를 장기 memory로 그대로 저장하지 않는다.
- 최종 요약은 짧은 handoff 중심으로 남긴다.
- 장기 정책은 PROJECT HOT 또는 PROJECT FORBIDDEN으로 명시적으로 저장한다.
- 임시 디버깅 과정, 긴 테스트 출력, raw response, credential, 로컬 DB 값은 저장하지 않는다.
- Codesight raw output은 저장하지 않는다.
- 자동 요약 내용이 Source of Truth와 충돌하면 Source of Truth를 우선하고 memory를 stale로 표시한다.
### 저장할 수 있는 memory
- 새로 확정된 프로젝트 정책
- 반복 회귀 원인
- 금지된 구현 방식
- 다음 작업자가 알아야 할 짧은 handoff
- 향후 에이전트 작업에 반복적으로 영향을 줄 결정
- stale 가능성이 확인된 과거 결정
- 다음 세션에서 이어서 작업하기 위한 짧은 세션 요약
### 저장하지 않는 memory
- API key, app secret, token, credential
- 계좌번호 전체, 주민번호, 식별 가능한 민감정보
- raw API response
- local DB 내용
- agent 실행 로그 전문
- 긴 테스트 출력
- 전체 작업 보고서 전문
- 임시 디버깅 메모 전체
- 곧 바뀔 가능성이 높은 구현 세부사항
- generated Codesight raw output
- Codex/Cursor/Claude 세션 전체 원문
### Memory 형식
memory는 짧고 명시적으로 작성한다.
권장 prefix:
- **PROJECT HOT**: 현재 유효한 작업 규칙
- **PROJECT FORBIDDEN**: 금지된 구현 방식
- **PROJECT HANDOFF**: 다음 작업자가 알아야 할 짧은 인계
- **PROJECT STALE**: 더 이상 유효하지 않은 과거 결정
- **PROJECT SUMMARY**: 다음 세션 연결을 위한 짧은 세션 요약
예시:
- PROJECT HOT: Workspace-affecting mutations must update local state, not only refresh the router.
- PROJECT FORBIDDEN: Do not restore deprecated fallback path.
- PROJECT HANDOFF: Current work stopped after adding provider ingest tests; next step is wiring mapper integration.
- PROJECT SUMMARY: Session focused on docs, Codesight/wiki, and agentmemory policy; Source of Truth remains AGENTS.md and docs.
---
## OmO / LazyCodex 사용 정책
OmO / LazyCodex는 Codex lifecycle 보조 hook/plugin이다. Source of Truth가 아니다.
- OmO를 SparkShell 자동 압축 도구로 전제하지 않는다.
- Codex Desktop에서는 SparkShell은 CLI에서만 사용 가능한 것으로 보이며, 기본 Bash 출력에 자동 개입한다고 가정하지 않는다.
- `ulw` 또는 `ultrawork` 키워드는 긴 작업 모드 유도에 사용할 수 있다.
- OmO hook/plugin 동작은 실제 실행 결과로 확인한다.
- OmO 결과가 `AGENTS.md` 또는 `docs/**`와 충돌하면 `AGENTS.md`와 `docs/**`를 우선한다.
- OmO가 없거나 동작하지 않아도 작업은 `AGENTS.md`와 docs 기준으로 진행한다.