OpenHands Skills와 AGENTS.md를 함께 사용할 때는 항상 적용할 짧은 규칙을 AGENTS.md에 두고, 특정 작업에서만 필요한 지식과 절차를 Skills에 넣어야 합니다. Xcode 빌드, 서명, 시뮬레이터와 실제 기기 검증은 어느 쪽에도 맡기지 말고 별도의 맥 검증 관문으로 분리해야 합니다.

이 글은 저장소 유지 관리자, iOS 개발자, 플랫폼 엔지니어와 보안 담당자를 위한 안내입니다. 공통 규칙을 통일하려는 사람은 AGENTS.md의 범위를, 업무별 지식을 나누려는 사람은 OpenHands Skills의 범위를 확인하면 됩니다.

마지막 확인은 2026년 9월 6일이며, 현재 OpenHands 문서와 애플의 Xcode 문서를 기준으로 정리했습니다. OpenHands의 Skills 공식 안내에서는 Skills를 현재 방식으로 설명하고 있으며, 일부 Microagents 경로는 이전 형식 또는 사용 중단 경로로 다뤄집니다.

먼저 정해야 할 것은 파일 형식이 아니라 규칙의 수명입니다

저장소에서 모든 작업이 알아야 하는 내용은 다음처럼 짧고 확인 가능해야 합니다.

  • 저장소가 해결하는 문제
  • 주요 디렉터리와 진입점
  • 기본 설치 명령
  • 반드시 통과해야 하는 자동 통합 검사
  • 테스트를 실행하기 전에 지켜야 할 공통 제한
  • 변경하면 안 되는 민감한 경로

이 내용은 작업마다 달라지지 않으므로 AGENTS.md에 두는 편이 적합합니다. 반대로 결제 모듈을 수정할 때만 필요한 규칙, 특정 화면 프레임워크의 구현 순서, 네트워크 계층의 오류 해석처럼 조건부 지식은 Skills에 넣어야 합니다.

AGENTS.md가 긴 개발 문서가 되면 모든 요청에 불필요한 내용이 따라옵니다. 반대로 공통 규칙을 Skills에만 넣으면 에이전트가 해당 Skill을 불러오지 않은 작업에서 중요한 제한을 놓칠 수 있습니다. 따라서 저장소 파일, 실제 작업 흐름, 현재 자동 통합 검사 설정을 규칙의 근거로 삼아야 합니다.

OpenHands Skills와 AGENTS.md의 차이는 적용 범위에서 갈립니다

OpenHands의 개발자용 Skill 안내에서는 Skill을 특정 지식과 실행 절차를 묶어 필요할 때 활용하는 방식으로 설명합니다. 핵심은 파일 위치보다 호출 조건입니다. Skill 설명만 읽어도 에이전트가 언제 이 지식을 사용해야 하는지 판단할 수 있어야 합니다.

AGENTS.md에 넣을 내용

  • 모든 변경에 적용되는 코딩 규칙
  • 저장소의 기본 구조
  • 공통 설치와 검사 명령
  • 변경 전후에 확인할 파일
  • 자동 통합 검사에서 요구하는 최소 조건

Skill에 넣을 내용

  • 특정 iOS 프레임워크의 구현 순서
  • 화면, 네트워크, 데이터 저장 모듈별 작업 절차
  • 자주 발생하는 오류와 확인 순서
  • 특정 테스트 대상이나 시뮬레이터를 선택하는 방법
  • 관련 스크립트, 참고 자료와 도구 설정

두 파일에 같은 내용을 복사하지 않는 것도 중요합니다. 예를 들어 AGENTS.md에는 “변경 뒤 해당 테스트를 실행한다”만 쓰고, iOS Skill에는 어떤 테스트 대상을 어떤 순서로 실행할지 적을 수 있습니다. 이렇게 해야 규칙이 충돌했을 때 어느 쪽을 고쳐야 하는지 분명해집니다.

iOS 팀은 Xcode 절차를 전부 공통 규칙에 넣지 않아야 합니다

iOS 저장소의 공통 규칙에는 프로젝트 진입점과 테스트 원칙을 적되, 모든 Xcode 명령을 한꺼번에 넣지는 않는 편이 안전합니다. 프로젝트마다 구성표, 테스트 대상, 의존성 설치 방식이 다르고, 실제 명령은 저장소의 프로젝트 파일과 자동 통합 검사 설정에서 확인해야 하기 때문입니다.

따라서 다음처럼 나누는 구성이 적절합니다.

  • AGENTS.md: 기본 프로젝트 위치, 기본 검사 실행 원칙, 서명 정보 취급 제한
  • iOS Skill: 구성표 선택, 테스트 대상 선택, 오류 해석, 시뮬레이터 준비 절차
  • 맥 검증 관문: 실제 빌드 결과, 테스트 로그, 서명 상태와 기기 실행 결과

애플의 구성표 설정 안내는 구성표가 빌드와 테스트 동작을 결정한다고 설명합니다. Xcode 테스트 결과 해석 안내도 실행 결과를 별도로 확인하는 흐름을 다룹니다. 그러므로 Skill에 명령을 적었다는 사실만으로 빌드와 테스트가 끝났다고 판단하면 안 됩니다.

OpenHands Microagents에서 Skills로 옮길 때는 바로 삭제하지 않습니다

OpenHands Microagents를 사용하던 저장소라면 새 Skills로 옮기는 방향을 검토할 수 있습니다. 다만 이전 파일을 먼저 지우는 방식은 피해야 합니다. 공식 문서에서 현재 명칭과 권장 경로가 바뀌었더라도, 실제 저장소의 로딩 결과와 호환 경로는 버전과 설정에 따라 달라질 수 있습니다.

다음 순서로 옮기면 회귀를 찾기 쉽습니다.

  1. 기존 Microagents가 제공하던 지식과 실행 절차를 목록으로 분리합니다.
  2. 항상 필요한 규칙을 AGENTS.md로 옮깁니다.
  3. 조건부 절차는 설명과 호출 조건을 포함한 SKILL.md로 다시 작성합니다.
  4. 같은 작업을 이전 구성과 새 구성에서 각각 실행합니다.
  5. 로그에서 어떤 규칙이 실제로 로드되었는지 비교합니다.
  6. 새 구성이 확인될 때까지 이전 경로를 되돌릴 수 있게 남겨 둡니다.

공식 스킬 구조와 개발 안내도 Skill을 단순한 문서 조각이 아니라 에이전트가 사용할 수 있는 지식 단위로 설명합니다. 이 때문에 파일 이름만 바꾸는 마이그레이션은 충분하지 않습니다.

Skill에 스크립트와 참고 자료를 넣을 때 보안 범위가 넓어집니다

OpenHands Skill은 설명문만 담는 파일이 아닐 수 있습니다. 스크립트, 참고 자료, 도구 설정과 연결될 수 있으므로 보안 검토도 마크다운 문장에만 한정하면 안 됩니다.

보안팀은 다음 항목을 함께 확인해야 합니다.

  • 스크립트에 실행 권한이 과도하게 부여되지 않았는지
  • 외부 입력을 명령으로 조합하지 않는지
  • 동적으로 내려받는 내용이 검증되는지
  • 도구 연결이 비밀 값이나 개인 키를 읽지 않는지
  • 저장소 바깥의 경로에 접근하지 않는지
  • 맥의 서명 자료와 인증서 저장 위치를 건드리지 않는지
  • 도구 호출 로그가 남고 실패 시 작업이 중단되는지

특히 Skill이 자동으로 실행된다는 문장을 보안 승인으로 오해하면 안 됩니다. 권한 범위와 실행 결과는 별도로 시험해야 합니다. OpenHands의 도구 연결과 확장 지점 안내를 확인한 뒤, 허용 목록과 차단 시험을 함께 운영하는 편이 좋습니다.

보안 정책과 개인정보 처리 기준을 팀 외부 서비스에도 적용해야 한다면 SSHMac의 개인정보 보호 정책도 함께 확인할 수 있습니다.

주의: “Skill이 이 명령을 실행했다”는 기록은 “명령이 안전했고 원하는 결과를 냈다”는 증거가 아닙니다. 실행 로그, 변경된 파일, 반환 코드와 차단 시험 결과를 함께 보관해야 합니다.

역할별 선택 점수는 이렇게 나뉩니다

아래 평가는 기능의 우열이 아니라 저장소 운영 목적에 따른 판단 기준입니다.

  • AGENTS.md: 공통 규칙 유지에 5점
  • 모든 작업에서 보아야 하는 규칙에 적합합니다.
  • 짧고 검증 가능한 내용만 남겨야 합니다.

  • 특정 모듈의 긴 절차를 담으면 관리 비용이 커집니다.

  • OpenHands Skills: 업무별 지식 재사용에 5점

  • 특정 프레임워크나 모듈 작업에 적합합니다.
  • 필요한 순간에만 불러와 문맥 부담을 줄일 수 있습니다.

  • 호출 조건이 모호하면 중요한 규칙이 빠질 수 있습니다.

  • 독립 맥 검증: 배포 전 증거 확보에 5점

  • 실제 Xcode 빌드와 테스트 결과를 확인합니다.
  • 서명과 기기 실행 권한을 분리해 검토할 수 있습니다.
  • 에이전트의 완료 보고만으로 통과시키지 않습니다.

플랫폼팀은 프로젝트 규칙, 사용자 수준 Skills, 이전 디렉터리 사이의 우선 관계를 버전별로 기록해야 합니다. 같은 이름의 규칙이 여러 위치에 있으면 보이지 않는 덮어쓰기가 발생할 수 있습니다. 공유 Skill에는 버전, 소유자와 변경 승인자를 붙이고, 마이그레이션 기간에는 이전 구성을 되돌릴 경로를 남겨야 합니다.

맥 검증으로 넘겨야 할 교부물을 정합니다

OpenHands가 코드를 수정한 뒤 맥 환경으로 넘길 때는 다음 자료를 하나의 묶음으로 보관하는 것이 좋습니다.

  • 변경 패치 또는 커밋 식별자
  • 의존성 파일의 변경 내역
  • 실행한 검사와 반환 결과
  • 아직 실행하지 않은 테스트 목록
  • 서명이나 인증서가 필요한 단계
  • 실제 기기 검증이 필요한 이유
  • 에이전트가 확인하지 못한 제한 사항

애플의 빌드와 실행 안내에 맞춰 빌드와 실행을 분리하고, 테스트와 서명도 별도 승인 단계로 두는 편이 좋습니다. 코드 생성은 낮은 위험 단계로 볼 수 있지만, 서명 자료 접근과 배포 권한은 같은 자동화 단계에 묶지 않아야 합니다.

iOS 저장소 규칙을 적용하기 전 확인 목록

  • [ ] AGENTS.md에 저장소 목적과 주요 경로만 남겼습니다.
  • [ ] 모든 작업에 필요한 설치와 공통 검사 규칙을 확인했습니다.
  • [ ] 특정 모듈 절차를 별도 SKILL.md로 분리했습니다.
  • [ ] Skill 설명만 보고도 호출 조건을 판단할 수 있습니다.
  • [ ] AGENTS.md와 Skill에 같은 규칙을 복사하지 않았습니다.
  • [ ] Xcode 구성표와 테스트 대상은 실제 프로젝트 또는 자동 통합 검사 설정에서 확인했습니다.
  • [ ] Microagents에서 옮긴 규칙을 이전 구성과 새 구성으로 비교했습니다.
  • [ ] Skill의 스크립트, 도구 연결, 민감 경로 접근을 검토했습니다.
  • [ ] 패치, 의존성 변화와 실행 로그를 맥 검증 담당자에게 전달했습니다.
  • [ ] 빌드, 테스트, 서명과 배포를 각각 승인할 수 있게 나눴습니다.

이 목록에서 하나라도 확인하지 못했다면 규칙을 더 추가하기보다 검증 경로를 먼저 고쳐야 합니다. OpenHands 운영 환경을 별도로 나누는 방법이 필요하다면 SSHMac 도움 센터에서 원격 맥 작업 환경과 관련된 안내를 확인할 수 있습니다.

현재 로컬 환경만으로 운영하면 Xcode용 맥을 다른 작업과 공유하게 되고, 실제 기기와 서명 자료의 사용 가능 시간도 팀 상황에 따라 달라집니다. 여러 개발자가 같은 환경을 번갈아 쓰면 재현되지 않는 상태 변화가 생기고, 에이전트가 만든 결과를 검증할 때 대기와 권한 조정이 반복될 수 있습니다. 장기간 고정된 고부하 작업이나 물리 기기 연결이 필수인 팀에는 자체 장비가 더 적합할 수 있지만, 단기간의 iOS 수정과 독립적인 Xcode 확인이 목적이라면 SSHMac의 맥 환경 임대가 작업 공간을 분리하는 현실적인 선택이 될 수 있습니다.

먼저 낮은 위험의 iOS 작업 하나를 골라 규칙 로딩 결과와 맥 검증 로그를 비교해 보십시오. 로컬 장비가 Xcode 검증을 계속 맡기 어렵다는 사실이 확인될 때 그때 원격 맥 작업 공간을 평가하는 순서가 비용과 권한 위험을 함께 줄입니다.