프로젝트와 작업 폴더
프로젝트는 작업할 로컬 폴더에 이름을 붙인 단위입니다. 프로젝트별로 대화가 모이고, AI의 작업 위치가 정해집니다.
프로젝트란
사이드바의 프로젝트 섹션에 프로젝트가 나열되고, 각 프로젝트 아래에 그 폴더에서 진행한 대화가 모입니다. 프로젝트를 연결하면 AI는 그 폴더를 기준으로 파일을 읽고 편집합니다.
프로젝트 목록은 앱 데이터 폴더의 projects.json에 저장됩니다(데스크톱: 앱 데이터 폴더, 런박스: ~/.helpycode/projects.json).
프로젝트 추가
사이드바에서 프로젝트 추가(또는 입력창 아래 프로젝트 추가 칩)를 누릅니다.
| 항목 | 설명 |
|---|---|
| 프로젝트명 | 필수. 최대 50자. 다른 프로젝트와 같은 이름은 사용할 수 없습니다. |
| 소스 폴더 | 선택 사항. "작업하고 싶은 소스 폴더 업로드"에서 폴더를 고릅니다. 선택하면 "선택한 폴더 위치에서 작업합니다."가 표시됩니다. |
만들기를 누르면 "프로젝트가 생성되었습니다!"가 표시됩니다.
폴더 검증
다음 경우에는 프로젝트를 만들 수 없습니다.
| 오류 | 원인 |
|---|---|
| 존재하지 않는 폴더입니다. | 선택한 경로가 폴더가 아니거나 없는 경우 |
| Helpy Code가 사용하는 폴더라 프로젝트 폴더로 지정할 수 없습니다. | 헬피코드의 작업 루트(문서/HelpyCode)나 임시 대화 폴더(chats)를 지정한 경우 |
| 이미 다른 프로젝트에 연결된 폴더입니다. | 같은 폴더를 두 프로젝트가 쓸 수 없습니다. |
| 폴더 이름으로 쓸 수 없는 이름입니다. | 프로젝트명이 폴더명으로 부적합한 경우 |
| 이미 있는 프로젝트 이름입니다. | 이름 중복 |
임시 작업 공간
프로젝트 없이 새 대화를 시작해도 됩니다. 이 경우 헬피코드는 작업 루트(문서/HelpyCode, 런박스는 ~/HelpyCode) 아래 chats 폴더에 새 임시 폴더를 만들어 그곳에서 작업합니다. 작업 루트 자체는 건드리지 않습니다.
- 입력창 아래 프로젝트 추가 칩으로 나중에 프로젝트를 연결할 수 있습니다. 이때 지금까지 입력한 텍 스트와 첨부 파일은 유지됩니다.
- 임시 폴더에서 만든 파일도 대화 내 생성파일 패널에서 볼 수 있습니다.
이름 변경과 삭제
프로젝트 항목의 메뉴({프로젝트} 메뉴)에서 선택합니다.
- 이름 변경: 새 이름을 입력하고 저장합니다.
- 삭제: 프로젝트를 삭제합니다. 로컬 파일과 기존 채팅은 삭제되지 않습니다.
프로젝트에서 새 대화
프로젝트 항목의 {프로젝트}에서 새 대화를 누르면 그 폴더에서 새 대화를 시작합니다. 대화가 없으면 "대화 없음"이 표시됩니다.
연결된 폴더가 사라졌을 때
연결한 폴더를 이동하거나 삭제하면 프로젝트 이름 옆에 (연결끊김) 이 표시되고, 대화 화면 위에 "프로젝트와 연결된 폴더가 유실되어 대화를 진행할 수 없습니다."가 나타납니다. 이때 입력창은 비활성화됩니다. 폴더를 원래 위치로 되돌리거나 폴더 복구 흐름으로 다시 연결하세요.
프로젝트별 설정 파일
프로젝트 폴더에 다음 파일을 두어 AI의 동작을 맞출 수 있습니다.
| 파일/폴더 | 용도 | 문서 |
|---|---|---|
AGENTS.md | 프로젝트 지침 | 지침 |
.opencode/skills/<이름>/SKILL.md | 프로젝트 스킬 | 스킬 |
.opencode/agents/<이름>.md | 프로젝트 서브에이전트 | 서브에이전트 |
AGENTS.md, .opencode/, .git/hooks 등 에이전트 구성 파일은 AI가 수정하려 하면 수락 모드와 상관없이 항상 확인을 요청합니다. 권한을 참고하세요.