# Astra와 Persona Harness 사용 가이드

## 무엇을 바꾸는가

Persona Harness는 개발자의 컨벤션, 철학, 승인한 결정을 작업 맥락에 전달하고,
선택한 워크플로의 완료 근거를 확인합니다. 모델 API를 대신 호출하는 SDK가
아닙니다. Astra 선택은 Codex/OpenCode 등 실행 호스트에서 설정하고, PH는
호스트별 스킬과 컨텍스트 경계를 유지합니다.

1.0.0은 이미 승인한 작업을 이어가는 공통 실행 지침을 제공합니다. 스킬을
읽었다는 이유로 새 권한을 만들지 않으며, 사용자가 준 권한을 매 단계 다시
묻지도 않습니다. 상태 질문과 정정은 진행 중인 목표에 반영합니다. 설명을
요청하면 현재 개념부터 설명하고, 중단 요청에는 즉시 해당 활동을 멈춥니다.

공식 기준은 [Astra 마이그레이션 가이드](https://developers.openai.com/api/docs/guides/latest-model)입니다.
문서 확인일은 2026-09-05입니다. 모델 접근 가능 여부는 호스트와 계정에서
확인해야 하며 패키지 설치만으로 Astra 사용 권한이 생기지 않습니다.

## Codex 설정

기존 `~/.codex/config.toml`의 다른 항목을 유지하면서 모델 관련 값만 검토합니다.
현재 reasoning이 지원되는 값이라면 마이그레이션만을 이유로 높이지 않습니다.
다음은 일반 개발 작업의 시작점입니다.

```toml
model = "gpt-6-astra"
model_reasoning_effort = "medium"
model_verbosity = "low"
```

`none` 또는 `minimal`을 사용했다면 Astra에서는 `low`부터 비교합니다.
복잡한 설계나 보안 검토는 해당 작업에서 effort를 높이고 실제 결과를 비교합니다.
API의 최대 context 숫자를 Codex 설정에 임의로 복사하거나 자동 압축을 끄지
않습니다. 호스트가 제공하는 모델 메타데이터와 압축 동작을 먼저 사용합니다.
권한, 샌드박스, 자격증명, 플러그인 설정은 모델 전환과 별개입니다.

설정은 다음 새 세션에 적용합니다. `codex --version`과 `codex features list`는
설치와 설정 파싱을 점검하는 명령이며, 실제 모델 호출 성공의 증거는 아닙니다.
역할별 `config_file`에 모델이 지정돼 있으면 그 설정도 확인합니다.
서브에이전트를 쓰지 않는 작업은 주 세션에서 완료합니다.

[Codex 설정 참고](https://developers.openai.com/codex/config-reference)

## 프롬프트는 이렇게 준다

원하는 결과, 유지할 제약, 완료 근거, 허용하는 작업을 짧게 적습니다.
매번 모든 컨벤션을 붙이지 않고 프로젝트의 승인된 자료를 참조합니다.

```text
회원별 알림 읽음 처리를 구현해줘.
기존 API 응답 형식과 auth 권한 경계를 유지하고,
.persona의 프로젝트 철학과 승인된 결정을 적용해.
구현, 관련 회귀 테스트, 리뷰까지 진행해.
결과를 바꾸는 요구사항이 모호할 때만 질문하고 나머지는 기존 패턴을 따라줘.
완료 시 변경 내용과 실제 검증 결과를 알려줘.
```

아직 제품을 정하지 않았다면 다음처럼 대화의 목적을 구분합니다.

```text
팀 알림 기능을 구체화하자. 한 번에 질문 하나와 추천안을 줘.
내가 이해하지 못하면 현재 질문부터 설명해.
이미 결정한 내용은 다시 묻지 말고, 구현은 요구사항 승인 뒤 시작해.
```

설계 검토는 구체적인 대상을 줍니다.

```text
이 알림 설계를 grill-me 방식으로 검토해줘.
중복 전송, 권한 누락, 장애 복구를 중심으로 질문하고 코드 수정은 하지 마.
```

상태를 물어보거나 요구사항을 정정해도 원래 목표가 자동 폐기되지는 않습니다.
작업을 중단하려면 `지금 인터뷰 중단`, `코드 변경 멈춰`처럼 대상을 말하면 됩니다.

## AGENTS.md 구성

전역 `~/.codex/AGENTS.md`에는 언어, 소통 방식, 승인 재사용, 검증 수준 같은
개인 기본값을 둡니다. 저장소 `AGENTS.md`에는 실제 기술, 폴더 경계, 테스트
명령, 보호할 규약, 완료 조건을 둡니다. 긴 기능 요구사항은 별도 문서에 두고
필요한 작업에서만 읽습니다. PH가 관리하는 블록 밖의 사용자 문장은 보존합니다.

```markdown
# 프로젝트 작업 기준

- .persona/project-profile.jsonc와 승인된 결정을 먼저 확인한다.
- 기존 도메인 경계와 API 응답 계약을 유지한다.
- 명확한 수정 요청은 구현, 관련 테스트, 리뷰까지 진행한다.
- 설명 요청은 현재 질문부터 설명하고, 중단 요청은 즉시 따른다.
- 같은 범위에서 이미 받은 승인을 다시 묻지 않는다.
- 검증은 변경 범위에 맞춘다. 필수 CI는 생략하지 않는다.
- 실패한 검증을 성공으로 표현하지 않고 남은 원인과 상태를 설명한다.
```

프로젝트에 맞는 실제 명령을 위 목록에 추가합니다. Java 프로젝트라면 Gradle
태스크를, PH 자체 소스라면 TypeScript/Vitest 검사를 적습니다. 설치 도구가
npm이라는 이유만으로 소비자 프로젝트를 Node 앱이라고 판단하지 않습니다.
또한 스킬 파일의 절차를 사용자 요청보다 우선하는 추가 권한 체계로 만들지
않습니다. 충돌이 생기면 해당 파일과 문구를 설명합니다.

Codex는 전역 지침과 프로젝트 경로의 지침을 조합하며, 같은 위치에
`AGENTS.override.md`가 있으면 일반 `AGENTS.md`보다 먼저 선택합니다.
하위 폴더 지침도 함께 점검합니다.
[공식 AGENTS.md 안내](https://developers.openai.com/codex/guides/agents-md)

## 철학 주입과 실행 권한

새 프로젝트의 compact shared-skill routing과 project philosophy guidance는
각각의 설정을 따릅니다. legacy `runtimeInjection`은 계속 기본 OFF입니다.
Context 또한 명시적으로 활성화합니다. 큰 컨텍스트를 한꺼번에 넣는 동작과
관련 스킬 하나를 선택하는 동작은 효과와 비용이 다르기 때문입니다.

사용자가 설정한 `false`, 직접 편집한 호스트 파일, 승인된 철학과 결정은
업데이트가 덮어쓰면 안 됩니다. 1.0.0의 OpenCode 자동 updater는 major가
달라지면 `major-approval-required`로 쓰기 전에 차단합니다. 같은 major의
업데이트만 다음 세션용으로 준비합니다. 이미 설치된 0.x에는 이 보호가 없으므로
새 릴리스만으로 예전 updater가 수정되지는 않습니다.

기존 프로젝트는 실행 중인 OpenCode를 종료하고 현재 설치된 PH로
`ph update disable --yes`를 실행해 자동 변경부터 끕니다. 1.0.0 게시와 검증이
완료된 뒤 다음처럼 정확한 버전을 선택해 명시적으로 전환할 수 있습니다.

```sh
npx --package=persona-harness@1.0.0 ph update enable --yes
```

이 명령은 PH가 소유권을 증명하는 OpenCode pin만 바꿉니다. 소유권 오류가 나면
설정이나 `.persona`를 삭제하지 말고 원인을 진단합니다. 프로젝트의 사용자
규칙을 강제로 덮어쓰는 우회 경로가 아닙니다. 진행 중인 세션은 기존 버전을
사용하고 새 세션에서 변경된 pin을 읽습니다.

## API를 직접 호출하는 별도 프로젝트

해당 프로젝트가 API 요청을 소유할 때만 적용합니다. Astra 도구 호출은
Responses API를 사용합니다. `temperature`, `top_p`, `top_logprobs`를
제거하고, 기존 Chat Completions의 `logprobs`와 Responses `include`의
`message.output_text.logprobs`도 제거합니다. GPT-5.5 이하에서
옮긴다면 캐시 설정은 `prompt_cache_retention` 대신
`prompt_cache_options.ttl`을 사용하는 새 계약을 검토합니다.

비동기 도구와 mid-turn steering은 서버가 실제로 pending call과 결과를
관리할 때 도입합니다. 스킬 문서에 설명을 추가했다고 이 API 기능이 구현된
것은 아닙니다. PH는 호스트의 API 요청 파라미터를 가로채서 바꾸지 않습니다.

## 검증할 실제 사용 시나리오

- 작은 수정: 스킬 안내 후 코드 확인, 수정, 관련 검증으로 이어지는가.
- 모호한 요구: 질문 하나를 하고, 설명 요청에 다음 질문으로 넘어가지 않는가.
- 중간 정정: 새 제약을 반영하면서 원래 목표를 유지하는가.
- 승인한 결정: 다시 질문하지 않고 적용하는가.
- 인터뷰 중단: 중단을 확인하는 또 다른 인터뷰 질문을 하지 않는가.
- 검증 실패: 근거 없이 완료라 말하지 않고 승인 범위 안에서 원인을 다루는가.
- 업데이트: 사용자 설정을 보존하며 major 전환을 무단 적용하지 않는가.

단위 테스트와 설치 검사는 파일 생성, 라우팅, 상태 전이를 확인합니다.
실제 모델이 이 지침을 따라 더 잘 작업하는지는 같은 과제와 평가 기준의
별도 호스트 관찰로 판단합니다. 1.0.0 버전명만으로 모든 호스트의 실사용,
토큰 절감, 제품 품질 개선이 검증됐다고 주장하지 않습니다.