--- locale: ko title: 워크스페이스 지침 description: AGENTS.md로 저장소별 에이전트 동작을, .qignore로 검색 대상을 제어합니다. sectionLabel: 개념 toc: - id: agentsmd와-agent-skills label: AGENTS.md와 Agent Skills - id: 로딩과-우선순위 label: 로딩과 우선순위 - id: 경로-감지 label: 경로 감지 - id: 지침-안전 label: 지침 안전 - id: qignore를-사용한-검색 label: .qignore를 사용한 검색 --- ## AGENTS.md와 Agent Skills 위치에 따라 자동 적용되어야 하는 저장소 지침에는 `AGENTS.md`를 사용하세요. 작업과 관련될 때만 검색하고 불러와야 하는 재사용 가능한 지침에는 Agent Skills를 사용합니다. 워크스페이스 루트 `AGENTS.md`는 전체 q 워크스페이스에 적용됩니다. 중첩 파일은 해당 디렉터리와 하위 경로에 적용됩니다. ## 로딩과 우선순위 q는 세션 시작 시 `/AGENTS.md`를 불러옵니다. 루트 지침은 일반 채팅, ACP 세션, 서브에이전트 모델 요청에 제공됩니다. 구조화된 도구 호출이 경로를 가리키면 q는 워크스페이스 루트부터 대상까지의 디렉터리를 확인합니다. 새 중첩 파일은 루트에서 하위 순으로 삽입되므로 해당 하위 트리에서 지침이 충돌할 때 더 깊은 `AGENTS.md`가 우선합니다. 도구 배치 직전에 새 중첩 파일을 찾으면 q는 배치를 멈추고 지침을 추가한 뒤 모델이 이를 검토하도록 도구 오류를 반환합니다. 모델은 여전히 적절한 호출만 다시 시도할 수 있습니다. 불러온 지침은 컨텍스트 압축 후에도 선행 지침 블록에 남습니다. 저장소 지침은 시스템 계약, q 내장 개발자 지침, 사용자의 명시적 요청보다 하위입니다. ## 경로 감지 q는 `path`, `paths`, `file`, `directory`, `source`, `destination`, `root`, `workdir`, `working_directory` 같은 구조화된 JSON 필드를 인식합니다. 셸 명령 문자열에서 경로를 추측하지는 않습니다. 불투명한 셸 명령만으로 중첩 디렉터리에 접근하면 해당 명령을 실행하기 전에 그 위치의 `AGENTS.md`를 자동으로 찾지 못합니다. ## 지침 안전 각 `AGENTS.md`는 64 KiB로 제한되며 NUL 바이트가 없는 UTF-8 텍스트여야 합니다. 너무 긴 유효 텍스트는 표시와 함께 잘립니다. 읽을 수 없거나 일반 파일이 아니거나 잘못된 텍스트이거나 워크스페이스 밖을 가리키는 심볼릭 링크는 무시됩니다. 이 검사는 지침 입력을 제한하지만 셸 명령을 샌드박스화하거나 저장소 지침을 사용자 및 시스템 정책보다 신뢰하게 만들지는 않습니다. ## .qignore를 사용한 검색 워크스페이스 루트 `.qignore`는 디렉터리 검색과 루트 목록을 필터링합니다. 주석, 부정 패턴, 루트 앵커, 디렉터리 접미사, `*`, `**`, `?` 와일드카드를 지원합니다. q의 `.q/` 메타데이터는 항상 검색에서 제외됩니다. `.qignore`는 접근 제어 경계가 아닙니다. 워크스페이스 안에 있는 명시적 경로는 모델 도구가 계속 읽을 수 있습니다. 경로 접근 자체를 막아야 한다면 운영체제 권한이나 격리를 사용하세요.