Files

koseokmin cb29b192b4 docs를 저장소로 되돌리고 계약 예제를 복원한다

5cfb8a1이 .gitignore에 docs/를 넣고 68개 파일을 지웠다. 그런데
AgentBuilderContractExampleTest, ToolBundleContractExampleTest,
ArchitectureDocumentContractTest는 docs/ 아래 계약 예제와 architecture
문서를 입력으로 직접 읽는다. 그 결과 clean clone에서 테스트 10건이
입력을 찾지 못해 실패했다.

제외 범위를 원래 의도대로 좁힌다. 에이전트 산출물(AGENTS.md, .agents/,
.codex/, docs/superpowers/)은 계속 제외하고 저장소 문서는 추적한다.

문서는 삭제 직전 상태(3de052a)를 기준으로 복원하고, 그 위에 main 코드와
대조해 어긋난 부분을 고쳤다.

- ADR-0007을 Superseded로 바꾸고 ADR-0013을 새로 쓴다. route당 Tool
  Service N개가 최종안이며, PortalToolRegistryClient가 이미 route별로
  N개를 유지하고 있는데 ADR-0007은 "bundles는 항상 한 항목"을 Accepted
  상태로 주장하고 있었다. ADR-0009 결정 4도 부분 대체한다.
- ADR-0008 파일 헤더가 Accepted였으나 ADR-0009가 이미 대체한 상태였다.
- 6078852의 endpoint 소유권 반전이 반영되지 않은 서술을 계약 v0.2,
  bundle 설정 예제, Tool 적재 안내에서 고친다.
- Portal registry 계약 v0.1과 route key 규약을 새로 문서화한다. 둘 다
  구현은 있는데 계약 문서가 없었다.
- MCP SDK 2.0.0 SBOM을 추가한다.

번호 주석: ADR-0011과 0012는 feature/mcp-integration이 Tool inputSchema
정책에 쓰고 있어 비워 둔다.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-22 23:27:56 +09:00

4.5 KiB

Raw Blame History

Codex 활용 및 저장소 공개 정책

목적과 책임

항목	소비자	저장소 포함
`AGENTS.md`	Codex의 모든 작업	아니오
`.agents/skills/`	조건에 맞는 Codex 작업	아니오
`.codex/config.toml`	신뢰된 프로젝트에서의 Codex 실행 환경	아니오
`docs/`	개발자와 리뷰어	예
`src/`	애플리케이션 빌드와 테스트	예
`deploy/`	배포 플랫폼	Secret이 없을 때만 예
`samples/`	개발자와 테스트	가짜 데이터일 때만 예

루트의 AGENTS.md, .agents/, .codex/는 Codex의 표준 탐색 지점이다. 보기 좋게 다른 하위 폴더로 옮기지 않는다. 사람을 위한 설명은 이 문서와 README.md에 둔다.

에이전트 지침(AGENTS.md, .agents/, .codex/)은 .gitignore가 제외한다. 에이전트 작업 산출물인 docs/superpowers/도 마찬가지다. 저장소 문서가 아니므로 반입 대상에 넣지 않는다.

docs/ 자체는 제외하지 않는다. AgentBuilderContractExampleTest, ToolBundleContractExampleTest, ArchitectureDocumentContractTest가 docs/ 아래 계약 예제와 architecture 문서를 입력으로 직접 읽기 때문이다. 문서를 저장소 밖에 두면 clean clone에서 이 세 계약 테스트가 입력을 찾지 못한다. 문서와 코드가 함께 검증되도록 같은 저장소에 둔다.

한때 docs/를 .gitignore에 넣은 적이 있고, 그 상태에서 계약 예제 16개와 architecture.md가 사라져 테스트 10건이 깨졌다. 에이전트 산출물만 좁게 제외하고 저장소 문서는 추적한다.

일상 작업 흐름

일반 작업은 루트 AGENTS.md 규칙을 따른다.
JSON-RPC, MCP method, Tool Registry, Tool 실행, trace log, Spring profile, OpenShift 배포를 변경할 때는 $verify-mcp-server-change를 명시적으로 호출한다.
Skill은 코드와 관련 테스트를 읽고 영향 계약을 확인한 뒤 최소 변경과 Gradle 테스트를 요구한다.
반복 작업이 세 번 이상 안정적으로 반복되면 새 skill 후보로 검토한다. 임시 작업, 일회성 지침, 개인 메모는 skill로 만들지 않는다.
작업 중 발견한 규칙은 재현·검토된 뒤에만 AGENTS.md, skill reference, 또는 설계 문서에 반영한다.

예시:

$verify-mcp-server-change
tools/call의 인자 검증을 변경하고 관련 테스트와 문서를 갱신해 줘.

Codex 설정 정책

개인 전역 Codex 설정에는 선호 모델, approval policy, sandbox mode, 개인 MCP 서버, 로컬 경로, 인증 정보를 둔다. 이 내용은 저장소에 올리지 않는다.

프로젝트 .codex/config.toml은 다음 조건을 모두 충족할 때만 추가하고 Git에 포함한다.

모든 팀원이 동일하게 적용해야 한다.
프로젝트 고유의 설정이다.
비밀정보, 개인 경로, 개인 권한 선호, 개인 MCP 연결이 없다.
일반 코드 변경처럼 리뷰할 수 있다.

현재 이 프로젝트는 위 조건에 해당하는 공유 Codex 실행 설정이 없으므로 .codex/config.toml을 사용하지 않는다. 프로젝트 설정이 필요한 시점에는 팀 검토 후 .gitignore의 해당 예외 규칙을 함께 변경한다.

GitHub 게시 전 점검

기본 공개 범위는 private로 한다. 공개 전환은 조직 정책, 내부 명칭, 배포 정보, 계약 문서, 샘플 데이터 검토 후 별도 결정한다.
AGENTS.md, .agents/skills/, 소스, 테스트, 가짜 샘플, 비밀정보 없는 배포 명세와 문서는 커밋한다.
.env, 인증서, keystore, Secret manifest, 실제 고객·운영 데이터, 개인 Codex 설정은 커밋하지 않는다.
첫 push 전에 Secret 검색을 실행하고, GitHub에서는 secret scanning, push protection, Dependabot, 기본 브랜치 보호를 활성화한다.
외부 공개가 확정되면 LICENSE, SECURITY.md, CONTRIBUTING.md와 공개용 샘플·문서를 추가한다.

구조 확장 기준

docs/decisions/: 장기 설계 결정이 실제로 발생할 때 ADR을 추가한다.
src/<subtree>/AGENTS.md: 특정 하위 모듈의 명령이나 규칙이 루트와 달라질 때만 추가한다.
.agents/skills/<name>/: 반복되고 안정적인 작업 절차가 생길 때만 추가한다.
.codex/hooks/: 지침과 테스트로 보장할 수 없는 결정적 정책을 강제해야 할 때만 추가한다.

빈 폴더나 자동 누적 lessons.md는 만들지 않는다.

4.5 KiB Raw Blame History