지침(AGENTS.md)
AGENTS.md에 규칙을 적어 두면 AI가 매 대화에서 읽고 따릅니다. 코딩 표준, 아키텍처 결정, 선호 라이브러리, 검토 체크리스트를 적는 용도입니다.
어떤 파일을 읽나요
헬피코드의 AI 엔진은 다음 지침 파일을 읽습니다.
| 범위 | 파일 | 설명 |
|---|---|---|
| 프로젝트 | AGENTS.md | 프로젝트 폴더에서 위쪽으로 올라가며 찾습니다. 여러 상위 폴더에 있어도 가장 먼저 찾은 파일 하나만 사용합니다. |
| 전역 | <설정 폴더>/opencode/AGENTS.md | 모든 프로젝트에 적용됩니다. 설정 폴더 위치는 설정 참조를 보세요. |
| (호환) | CONTEXT.md | 더 이상 권장되지 않는 이전 형식입니다. |
warning
CLAUDE.md는 읽지 않습니다. 헬피코드는 엔진의 Claude Code 프롬프트 호환 기능을 꺼 두었습니다(OPENCODE_DISABLE_CLAUDE_CODE_PROMPT). 이미 CLAUDE.md만 있다면 같은 내용을 AGENTS.md로 옮기거나 AGENTS.md에서 참조하세요. 파일 자체는 보호 파일이므로 AI가 수정하려면 확인을 거칩니다.
엔진은 앱이 추가한 안내 파일(<설정 폴더>/instructions.md)도 지침으로 읽습니다. 이 파일은 "MCP 서버는 opencode.json의 mcp 필드에서만 읽는다"는 내용을 AI에게 알려 줍니다. 직접 수정하지 마세요(앱이 시작할 때 다시 씁니다).
/init으로 시작하기
새 프로젝트에서 입력창에 /init을 실행하면 AI가 프로젝트를 분석해 AGENTS.md 초안을 만들어 줍니다. AGENTS.md는 보호 파일이므로 만들거나 수정할 때 확인(guard) 패널이 나옵니다.
잘 쓰는 법
- 구체적으로 적으세요. "코드를 깔끔하게"보다 "함수는 40줄 이하, 컴포넌트는
features/아래에 둔다"가 따르기 쉽습니다. - 명령을 적어 두세요. 빌드, 테스트, 린트를 실행하는 정확한 명령을 적으면 AI가 추측하지 않고 실행합니다.
- 짧게 유지하세요. 지침은 매 대화의 컨텍스트를 차지합니다. 자주 바뀌거나 길고 절차적인 내용은 스킬로 옮기세요.
- 모순되는 규칙이 없도록 주기적으로 정리하세요.
예시
# 프로젝트 지침
## 명령
- 설치: `pnpm install`
- 테스트: `pnpm test` (변경 후 항상 실행)
- 린트: `pnpm lint`
## 규칙
- 새 컴포넌트는 `src/features/<기능>/components/` 아래에 만든다.
- 사용자에게 보이는 문구는 `ko.json`, `en.json`에 함께 추가한다.
- 커밋 메시지는 `type(scope): summary` 형식을 쓴다.
컨텍스트가 바뀔 때
지침은 대화를 시작할 때 AI에게 전달됩니다. AGENTS.md를 고친 뒤에는 새 대화에서 반영됩니다. /compact로 대화를 요약하면 지침이 다시 포함됩니다.