워크스페이스 지침

AGENTS.md와 Agent Skills

위치에 따라 자동 적용되어야 하는 저장소 지침에는 AGENTS.md를 사용하세요. 작업과 관련될 때만 검색하고 불러와야 하는 재사용 가능한 지침에는 Agent Skills를 사용합니다.

워크스페이스 루트 AGENTS.md는 전체 q 워크스페이스에 적용됩니다. 중첩 파일은 해당 디렉터리와 하위 경로에 적용됩니다.

로딩과 우선순위

q는 세션 시작 시 <workspace>/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는 접근 제어 경계가 아닙니다. 워크스페이스 안에 있는 명시적 경로는 모델 도구가 계속 읽을 수 있습니다. 경로 접근 자체를 막아야 한다면 운영체제 권한이나 격리를 사용하세요.