코딩을 시작하기 전에 꼭 한 번 읽어 보시기를 권합니다 — 온보딩과 프로필에 링크가 있고, 읽지 않았다고 막지는 않습니다. 저장소 안의 MATE.md(사용 안내서)에도 같은 내용이 들어 있습니다.
1. 작업 방식
| 원칙 | 왜 |
|---|---|
| main에서는 작업하지 않는다 — 작업은 늘 브랜치에서. "배포해줘" 하면 Claude가 main에 합쳐 배포한다 | main은 지금 서비스 중인 코드다. 실수가 곧 장애가 된다. 훅이 main 커밋을 막는다 |
| 배포는 "배포해줘" 한마디로 — 직접 push·merge 하지 않는다. Claude가 보안 점검 → 배포까지 이어서 한다 | 손으로 하면 점검을 건너뛰기 쉽다. 되돌리기도 "이전으로 되돌려줘" 한마디 |
| 한 저장소 = 한 앱 = 한 주소 — 목적이 다르면 새 저장소를 만든다 | 저장소 이름이 곧 주소이고 배포 단위다 |
| 작게 자주 배포한다 — 한 번에 조금씩 바꾸고 확인한다 | 문제가 나면 어디서 났는지 바로 안다. 되돌리기도 한 번에 끝난다 |
| 앱 설명서(README)를 최신으로 — 제목·설명(100자)·무엇을 하나·화면·쓰는 법. Claude가 배포 때마다 갱신한다 | 앱 화면과 대시보드에 그대로 보인다. 다른 사람이 인수받을 때 유일한 문서다 |
2. 비밀값과 데이터
| 원칙 | 왜 |
|---|---|
API 키·비밀번호·토큰은 코드에 넣지 않는다 — .env.example에 이름만 적고(이름 규칙은 그 파일 머리말), 값은 저장소 화면 → 환경 변수에 넣거나 Claude에게 "env 올려 줘" |
GitHub에 올라간 키는 유출된 것으로 본다. 훅과 배포 파이프라인이 막는다 |
| 실수로 키를 올렸으면 새로 발급받는다 — 지우는 것만으로는 부족하다 | 커밋 기록에 남는다 |
| 고객 원본 데이터(csv·xlsx·DB 덤프)는 저장소에 올리지 않는다 | 개인정보·계약 데이터다. 저장소에는 코드만 |
데이터베이스는 Mate의 PostgreSQL만 — 앱을 연결하면 고객사 데이터베이스가 자동으로 붙는다(DATABASE_URL). SQLite·파일 DB는 쓰지 않는다 |
파일 DB는 재배포·서버 해지 때 사라진다. Mate 데이터베이스는 앱을 지워도 유예 기간 동안 남고, 같은 고객사 앱을 다시 연결하면 되살아난다 |
| 파일은 서버 디스크가 아니라 스토리지에 — 이미지·첨부·내보내기는 Mate 스토리지로 저장한다 | 서버는 언제든 다시 만들어지므로 디스크에 둔 파일은 사라진다 |
로컬용 .env는 내 컴퓨터에만 — 커밋되지 않는다(.gitignore) |
서버의 비밀값은 배포 때 Mate가 앱에만 넘긴다 |
3. 배포 전 보안 점검
| 원칙 | 왜 |
|---|---|
| 이슈 0건일 때만 배포 — Claude가 점검 결과를 항상 알린다. "그냥 배포해"라고 해도 이슈가 남아 있으면 배포하지 않는다 | 배포 파이프라인이 같은 검사를 한 번 더 한다. 우회하는 길은 없다 |
| 점검 항목 — 하드코딩된 비밀값, 데이터 파일, 취약한 의존성, 열린 관리자 경로, 외부로 나가는 요청 | 마케팅 앱은 외부에 열린다. 한 번 새면 회수가 안 된다 |
| 점검에 걸리면 Claude가 알려 준 대안대로 — 환경 변수로 옮기기, 키 재발급, 파일 제거 | 원칙마다 정해진 대안이 있다 |
4. 손대지 않는 것
| 원칙 | 왜 |
|---|---|
배포 파일과 Claude 설정 — Dockerfile · docker-compose.yml · deploy/ · .github/workflows/ · .claude/ · CLAUDE.md |
Mate가 관리하고 매일 자동으로 최신화한다. 고치면 다음 갱신에 덮이거나 배포가 막힌다 |
| GitHub 웹에서 권한·설정 바꾸기 — 협업자 추가·public 전환·설정 변경은 포털에서만 | 포털이 권한의 원천이다. 밖에서 바꾸면 드리프트로 잡히고 되돌려진다 |
| 서버·데이터베이스·스토리지·도메인을 따로 만들기 — 필요하면 관리자가 포털에서 | 비용과 보안이 Mate 밖으로 나간다 |
git push --force · git reset --hard |
다른 사람의 작업이 사라진다. Claude도 막혀 있다 |
5. 막혔을 때
- Claude가 "이건 안 됩니다"라고 하면 위 원칙 중 하나다. 우회하지 말고 Claude가 알려 준 대안대로 간다.
- 배포가 실패하면 저장소 화면 이슈에 이유가 남는다. 고치면 해결 표시.
- 권한·환경 변수·서버 접속(SSH)이 필요하면 팀 관리자에게. 그 외는 저장소 안
MATE.md, 이 문서, 데이터컨설팅팀.
Mate — 데이터컨설팅팀 · https://mate.madup.app/docs/principles · Mate 가 무엇이고 무엇을 할 수 있는지는 Mate 소개서에 있습니다.