결론#

github.com/rosaic-ai/rosaic-agent-skills. 태스크를 마치면 Jira 이슈에 완료 보고를 쓰고 그 세션의 대화 기록을 증거로 첨부하는 스킬. Claude Code / Codex 양쪽에서 같은 파일이 동작한다. 만드는 과정에서 반복해서 틀린 것들을 남긴다.

규칙을 늘리면 안 되는 지점#

작업 규칙(태스크 시작 선언, 한 태스크 한 세션, 완료 시 보고)을 문서에 박을지 검토했으나 넣지 않았다. 근거:

• 못 지키는 이유가 많다 — 재부팅, 실기 이동, 며칠 걸리는 조사, 컨텍스트 팽창 회피
• 위반을 이유로 거부하면 사람들이 위반을 숨긴다. 불완전한 로그만 붙이게 된다
• 못 지키고 어겨도 막지 않을 규칙은 일을 하지 않는다

대신 에이전트가 모르면 묻게 했다. 이슈 키가 하나면 확정하고, 여러 개거나 없으면 그때만 묻는다. 등장 횟수로 자동 선택하지 않는다 — 참고로 언급한 이슈가 더 자주 나온다.

다만, 안전이 걸린 곳에는 절차가 필요하다 (2026-08-11 수정)#

"절차를 쓰지 말고 템플릿만 맞추게 하라"로 한 번 갔다가 되돌렸다. 절차를 통째로 걷어낸 버전에서 증거 인용이 틀린 보고서가 실제로 게시됐다. 공식 스킬 조사에서도 90.6%가 절차 표지를 쓴다. 정확성·안전성·일관성·외부 상태를 좌우하는 핵심 절차만 남기는 게 맞다. 최종 5단계:

1. 스크럼 번호 확정   ← 세션에 없으면 추정 금지, 묻는다
2. 관련 대화 추출
3. 내용 정리          ← 산출물 = (근거 문장, 턴 번호) 쌍
4. 보고서 작성        ← 턴 번호는 3에서 온 것만 쓴다
5. 확인               ← 이슈 · 근거 쌍 · 본문 한 화면

3단계가 핵심이다. 보고서를 먼저 쓰고 턴 번호를 나중에 붙이면 반드시 틀린다 — 실제로 첨부를 교체하면서 인용 번호를 기계적으로 찾아바꾸기만 해 [4] [8] 이 무관한 턴을 가리키는 사고가 났다.

완료 보고에서 반복해 틀린 것 넷#

1. 완료 조건을 만들어 넣었다. 이슈에 완료 조건이 없으면 세션에서 도출해 체크하게 했었다. 스스로 기준을 세우고 스스로 충족 판정하는 구조다. → 이슈에 있을 때만 대조하고 없으면 슬롯 생략.

2. 산출물이 없었다. 결정 슬롯은 산출물 안의 내용이지 산출물이 아니다. 완료 보고인데 무엇이 나왔는지가 없어 3주 뒤 이어받는 사람이 결과물을 못 찾는다. → 완료 결과 슬롯을 맨 앞에.

3. 결과에 경로만 적었다. docs/기능정의서.pdf v1.0 확정 은 독자가 문서를 열어야 안다. Jira 코멘트를 보는 사람은 대부분 안 연다. → 결과는 내용, 경로·버전은 근거 슬롯.

4. 슬롯이 11개였고 중복이 많았다. 결정↔판단전환, 대안↔판단전환, 제약↔겪은문제↔미해결, 영향범위↔다음. → 6슬롯, 결과 우선: 완료 결과 → 배경·목표 → 수행·검증 → 주요 결정 → (겪은 문제) → 잔여·후속 → 근거.

대화 로그: 무엇이 증거인가#

위임 rollout을 통째로 배제하는 규칙은 과했다 (2026-08-11 수정). 처음엔 "Codex 서브에이전트 rollout 은 대화가 아니다 — 사람 대화는 부모 세션에 있다"를 절대 규칙으로 박았다. 위임 rollout만 첨부했다가 "저게 어딜봐서 대화 로그냐"는 지적을 받은 뒤였다.

그런데 같은 작업을 실측해 보니 핵심 설계 근거가 위임 쪽에 훨씬 많았다:

'state_brief' 언급:  부모 1회  vs  위임 6회
'부분' 분류 언급:    부모 2회  vs  위임 17회

부모에 지시가 있고, 위임에 판단이 있다. 둘 다 증거다. 규칙을 절대 금지에서 판단 사항으로 강등했다. 판별 신호는 유지: 사람 발화 1~2건 + 첫 발화가 역할 지시문이면 위임. cwd가 부모 scratchpad를 가리키는 건 보조 신호(부모 cwd가 프로젝트 루트면 안 잡힌다).

막을 수 있었던 유일한 지점은 확인 단계다. 업로드 전 화면에 첨부에 담긴 사람 발화 목록 + (근거 문장, 턴 번호) 쌍을 함께 보여준다.

걷어낼 잡음#

같은 구간이 62,159자 → 39,252자가 됐다. 발화 자체는 자르지 않는다.

현재 세션을 결정론으로 확정하는 법#

스킬은 자기 세션 ID 를 모른다. "가장 최근 갱신 파일" 추측은 확인이 필요해 흐름을 끊는다.

해법: 임의 nonce 를 인자로 넘겨 스크립트를 부른다. 도구 호출의 인자는 호출 즉시 세션 기록에 적히므로, 그 토큰이 든 파일이 곧 현재 세션이다. flush 지연이 있어 0.4초 간격 8회 재시도한다.

# 에이전트가 매번 새 값을 만들어 리터럴로 직접 박는다
session-log.py --issue SCRUM-411 --current --nonce a7f3c91e5b > /tmp/log.md

셸 변수로 넘기면 안 된다. 아래 "함정 1" 참조 — 이 트릭이 통째로 무력화된다.

nonce 트릭의 함정 셋 — 전부 실패가 조용하다 (2026-08-11 실측)#

함정 1 — 셸 변수는 확장 전 문자열로 기록된다#

NONCE=$(openssl rand -hex 5)
session-log.py --current --nonce $NONCE      # ✗ 절대 매칭 안 됨
session-log.py --current --nonce a7f3c91e5b  # ✓ 확정

기록에 남는 건 명령이 타이핑된 그대로다. 셸 확장은 실행 시점이라 기록에는 $NONCE 리터럴만 찍힌다. 실측:

'--nonce $NONCE' 기록됨: 35회
'a7f3c91e5b' 기록됨:      3회

함정 2 — 못 찾았을 때 폴백하면 남의 세션을 집는다#

매칭 실패 시 "최신 파일"로 조용히 넘어가면, 서브에이전트를 병렬로 돌리는 환경에서 그 최신 파일은 대개 남의 rollout이다. 실제로 현재 대화가 아니라 무관한 Codex rollout이 선택됐다. --nonce를 주었는데 못 찾으면 비0으로 죽어야 한다. (안 준 경우의 추측 폴백은 과거 세션 작업용으로 정당하다.)

함정 3 — 문서의 예시값이 오염원이 된다#

스킬/문서 본문은 로드되는 순간 그 세션 기록에 통째로 적힌다. SKILL.md에 박아둔 형식 예시 nonce가 스킬을 부른 모든 세션에 남는다. 시간이 갈수록 매칭 세션이 늘어나고, 예시값을 교체하지 않은 에이전트는 남의 세션을 "확정"으로 집는다. 문서 예시는 실행 불가능한 자리표시자여야 하고, 스크립트는 nonce가 2개 이상 매칭되면 실패해야 한다.

일반화 — 같은 병의 네 번째 변종#

Codex 세션 ID 앞 8자리(UUIDv7)도 같은 문제였다. 앞 8자리는 48비트 ms 타임스탬프의 상위 32비트라 해상도가 약 65초다. 그 안에 시작된 두 세션은 반드시 충돌하고, 서브에이전트 병렬 실행에서 일상적으로 발생한다. 그래서 메타 마커 session= 은 전체 UUID 36자로 갔다(첨부 파일명은 YYYYMMDD-HHmmss 가 함께 있어 8자리 유지).

규칙: 프리픽스·토큰·축약 ID로 무언가를 지목할 때는 매칭 개수를 세고, 1이 아니면 실패시켜라. 조용한 오선택은 검증 경로 없는 잘못된 증거를 만든다.

레닥션은 문서가 아니라 테스트로 고정한다#

templates/session-log.md 가 치환하겠다고 적어둔 패턴 중 Bearer 토큰·PEM 키·고객 데이터 경로가 실제로는 미구현이었다. 문서는 막는다고 하고 구현은 안 막는데, 첨부는 기본값이 "생략 불가"였다. 배포 차단급 조합이다.

문서와 구현을 1:1로 맞추고 회귀 테스트 픽스처로 고정했다. 치환돼야 할 케이스와 치환되면 안 되는 오탐 케이스를 함께 넣는다 — 고객 경로 패턴은 좁히지 않으면 /home/insu/LG_project/README.md 같은 정상 경로까지 먹는다.

Jira 실측#

• v2 API 위키 마크업이 정상 렌더링된다. 표·코드블록·목록·(/)·(x) 이모지·[^첨부] 참조가 모두 ADF 노드로 변환된다. ADF 직접 조립 불필요
• 줄바꿈이 까다롭다. *라벨* 뒤에 빈 줄이 없으면 내용이 들러붙고, 불릿 없이 줄만 바꾼 항목은 한 문단으로 합쳐진다. 체크 항목도 * (/) 조건 으로 써야 한다
• 인라인 코드는 백틱이 아니라 {{중괄호}}
• 첨부 업로드 한도 1GB. 같은 이름 재업로드는 덮어쓰기가 아니라 중복 파일이라 파일명에 초 단위를 넣는다
• 이슈 타입 에픽 은 JQL issuetype="에픽" 으로 매칭되지 않는다. 조회 후 클라이언트에서 거른다

성과 집계에서 조심할 것#

완료 건수는 티켓 입도를 측정한다. LG PoC 실측: 전체(Subtask 포함) 기준 70건 대 6건이던 것이 작업 레벨만 세면 9건 대 6건이 된다. 한 사람만 Subtask 를 쓰고 나머지는 안 쓰기 때문이다. 집계는 작업 레벨로 고정하고 Subtask 는 세지 않는다.

관련: codex-cli-hooks-claude-code-compatible

Sagwan Revalidation 2026-08-31T12:41:56Z#

• verdict: ok
• note: 최근 수정된 설계 교훈이며 수치·권장안에 즉시 낡은 정황은 없다.

Sagwan Revalidation 2026-09-03T03:39:39Z#

• verdict: ok
• note: 최근 검증 이후 바뀔 외부 수치·권장안 의존이 작고 설계 교훈은 유효함

Sagwan Revalidation 2026-09-09T05:52:11Z#

• verdict: ok
• note: [chatgpt HTTP 404] {

Sagwan Revalidation 2026-09-11T20:30:33Z#

• verdict: ok
• note: 설계 원칙·절차 중심 내용으로 기술 시효가 길고, 2일 전 검증됐으며 변경된 사실관계 없음.

Sagwan Revalidation 2026-09-15T14:09:02Z#

• verdict: ok
• note: 최근 검증 뒤 핵심 절차·Jira 실측·권장안이 바뀐 정황 없음