왜? 중간 과정은 무엇이든 가능합니다. 최종 결론과 모든 자료에는 그 답이 있어야 하고, 없으면 기각합니다. 자료의 왜? 는 받는 사람이 그것으로 무엇을 하는가입니다. 답이 없는 내용은 넣지 않습니다. 업무와 공부를 가리지 않는 대전제입니다.
원하는 것은 개발자에게 있고, AI는 그것을 구체화하며 조언하고 실행하되 결정은 개발자가 합니다.
결정은 기록으로 남아 AI가 따르는 기준이 되고, AI의 작업물은 그 기록과 테스트에 대조해 바로잡습니다.
- 대외비 유출·머지·릴리즈·force push·기본 브랜치 직접 push·리소스 삭제는 실행 전에 막습니다
- 문장 표현과 문서 구조는 막지 않고 어긴 자리만 알립니다. 기계로 판정하면 정상인 것까지 걸리고 자동으로 고치면 뜻이 틀어집니다
- 막힌 자리에서 어시스턴트가 그 갈래를 담은 개방 명령을 만들어 건넵니다. 사용자는 절차를 외우지 않고 받은 한 줄을 실행하거나 직접 처리합니다
도구 실행 ─► 되돌릴 수 있나 ─┬─ 없다 ─► 차단 ─► 개방 명령 제시 ─► 사용자 실행
└─ 있다 ─► 실행 후 위반 위치 통지
효과: 승인한 행위와 통과한 행위가 어긋나는 순간을 실행 전에 잡습니다. 열린 권한은 갈래와 만료를 갖고 만료 시각이 지나면 스스로 닫힙니다.
- 공통 규칙은 이 레포에 두고 조직·팀 특화는 별도 플러그인에 둡니다
- 나누는 기준은 재사용 범위와 노출 경계입니다. 한 벌로 합치면 조직 전용 정보가 공개 표면에 노출됩니다
공통 · 이 레포 워크플로우 골격 · 작성 규칙 · 차단 규칙
│ 골격 상속
├─► 조직 · 개인 조직 전용 어댑터 · 개인 데이터 원천
└─► 팀 · 프로젝트 언어 컨벤션 · 브랜치 규칙 · 태스크 템플릿
효과: 규칙을 한 곳에서 고치고 받는 쪽은 필요한 지점만 재정의합니다.
- 세션을 마칠 때 교정을 추리고, 남기는 것은 셋뿐입니다: 환경 사실 · 되돌릴 수 없는 작업의 절차 · 추측할 수 없는 취향
- 판단 · 태도는 남기지 않습니다. 남겨 둬도 같은 실수가 줄지 않았습니다.
- 등재는 사람이 정하고, 기각한 것도 근거와 함께 남깁니다.
- 대화에서 바로잡은 용어는 글 · 말 예문과 함께 한 목록에 쌓아, 모든 세션이 같은 말을 쓰게 합니다. 같은 개념은 같은 용어로 써야, 이해한 것을 남에게 말로 설명할 때 뜻이 흐려지지 않습니다.
- 외부 시스템 파악도 같습니다. 접근하거나 문서를 읽기 전에 쌓아 둔 참조부터 찾습니다. 파악을 마친 세션이 결과를 참조 자산으로 남깁니다. 레슨런은 없으면 실수가 되풀이되는 것, 참조 자산은 없으면 같은 문서를 다시 찾아 읽어야 하는 것입니다.
교정 추리기 ─► 사실·절차·취향인가 ─┬─ 예 ─► 사실·모순·일반화 판정 ─► 등재 ─► 다음 작업이 읽음
└─ 아니오 ─► 판정 기록 한 줄
파악 시작 ─► 참조 자산 검색 ─► 없는 것만 파악 ─► 그 세션에 등재 ─► 다음 파악이 읽음
효과: 한 번 조사한 사실과 절차를 다음 작업이 다시 조사하지 않습니다 → 레슨런 자산화, ADR 0024
- 역할은 책임 할당 매트릭스(RACI)의 세 칸을 따릅니다. 알림(Informed) 칸은 대응을 검토 중이라 아직 두지 않습니다
- 전문가는 표준 근거와 실무 노하우로 설계 · 운영 전반에 의견을 내고 개발자가 반박합니다. 같은 반박이 두 번 나오면 그 기준을 고치고, 확정된 실무 케이스는 노하우로 쌓습니다
- 실무자는 위탁받은 산출물을 만들고, 그것이 옳은지는 판정하지 않습니다. 자기 산출물을 자기가 승인하지 않기 위해서입니다
| 역할 | RACI | 하는 일 | 하지 않는 일 | 자리 |
|---|---|---|---|---|
| 결정자 | Accountable | 계획 승인, 최종 확인. 작업마다 한 명 | 초고 작성, 실행 | 사용자 |
| 전문가 | Consulted | 표준 근거와 실무 노하우로 조언하고 반박받기 | 결정, 산출물 작성, 실행 | experts/*.md |
| 실무자 | Responsible | 위탁받은 산출물 만들기 | 옳은지 판정, 자기 승인 | agents/*-operator.md |
전문가 명부는 전문가 토론 이 정본입니다.
효과: 의견과 위탁이 한 이름으로 섞이지 않습니다. 판단 근거는 전문가 파일에, 실행 기록은 실무자 원장에 쌓입니다 → ADR 0019
- 처음 쓰는 기능 · 설정 · 외부 시스템의 동작은 대상 환경에서 효과를 관찰한 기록이 있어야 통과. 설정 값이 적혀 있는지 보는 검사와 문서의 「된다」는 관찰이 아님
- 관찰하는 단계는 틀렸을 때 되돌리는 비용으로 결정. 설계를 다시 해야 하는 전제는 설계 단계 PoC, 구현 안에서 바꿀 수 있는 디테일은 구현 단계 일회성 실험
- 실측에서 못 챙기는 디테일은 실무자가 수치로 보고, 넘어갈지 설계로 되돌릴지는 결정자가 판정
처음 쓰는 동작 ─► 틀리면 설계를 다시 하나 ─┬─ 예 ─► 설계 단계 PoC ─► 결과 없으면 설계에 못 들어옴
└─ 아니오 ─► 구현 단계 실측 ─► 안 되는 디테일은 보고 ─► 결정자 판정
효과: 오류 없이 무시되는 설정과 결과값만 정상인 경로가 「동작한다」로 남지 않습니다 → ADR 0023
- 착수 전에 답할 질문 한 문장·남길 결론 개수·분량 하한·상한·시각 요소 개수를 적습니다. 분량 값은 같은 유형 실측에서 나옵니다
- 신규 작성과 기존 문서 구조 변경 모두 이 게이트를 지납니다. 문장 한두 개 교정은 면제입니다
계획 ─► 초고 ─► 퇴고 ─► 교정 ─► 최종 확인
결정자 실무자 실무자 lint 결정자
- 계획과 최종 확인은 결정자가 합니다. 초고와 퇴고는 글쓰기 실무자 에게 맡깁니다
- 유형별 구조 · 분량 · 합격선은
profiles.md가 정본입니다
단계 이름은 국어과 교육과정의 쓰기 과정을 그대로 씁니다. 스킬 이름을 외우지 않아도 단계 이름으로 도달합니다.
효과: 완성 후에 공백이 드러나 재작성하는 왕복이 줄어듭니다 → ADR 0005
| 한계가 있는 자리 | 지금 상태 |
|---|---|
| 기준 모델 | 발화 분량·검증·위임 규칙은 Claude Opus 5 로 쓰면서 다듬었습니다. 규범과 비용 제약은 모델이 바뀌어도 유지되고, 모델 경향을 누르는 항목만 재판정 대상입니다 (구분) |
| 대상 하네스 | Claude Code 전용입니다. 플러그인 구조·훅·스킬 라우팅이 모두 Claude Code 의 것이라, Codex 등 다른 에이전트 하네스는 대응하지 않습니다 |
| 효과 | 효율이 올랐다는 주장은 넣지 않았습니다. 측정한 적이 없습니다 |
| 지표 | 레슨런 자산화의 지표는 항목만 정의하고 값은 비워 뒀습니다 |
| 적용 범위 | 아직 1인입니다. 팀 규모에서 검증되지 않았습니다 |
| 전문가 범위 | 분야를 하나씩 채우는 중입니다. 없는 분야를 물으면 그 사실을 말하고 멈춥니다. 환경 전용 분야는 로컬 오버레이로 더합니다 (목록) |
| 게이트 범위 | 세션 허용은 행위 갈래와 시간 둘로 열립니다. 승인하지 않은 갈래는 계속 차단됩니다 |
| 패턴 판정 | 표현 규칙은 정규식이라 활용형을 빠뜨리면 통과합니다 (#285) |
| 차단의 성질 | 도구 경계에서 명령 문자열을 봅니다. 방어 계층이지 보안 경계가 아닙니다 |
| 훅 비용 | 도구 호출마다 훅이 실행됩니다. 느린 기기에서는 지연이 보입니다 |
claude plugin marketplace add https://github.com/idean3885/claude-ops-agent.git
claude plugin install ops-agent@ops-agent새 세션부터 적용됩니다. 확인·갱신 방법과 시점별 동작은 설치하고 쓰는 법 에 있습니다.
| 문서 | 무엇의 정본인가 |
|---|---|
| docs/usage.md | 설치, 시점별 동작, 스킬·스크립트 목록. 나머지 문서 링크도 여기 |
| docs/design-philosophy.md | 설계 판단과 되돌린 결정 |
| docs/action-gate.md | 차단 규칙 |
| docs/lessons.md | 레슨런 수집·자산화, 재발 분석 |
| docs/adr/ | 개별 결정 기록 |
| CLAUDE.md · CONTRIBUTING.md | 이 레포의 작업 규칙, 수정 플로우(이슈 전 갭 확인 · 컨펌 전 재검사), 반영 경로 |
근거 없는 규칙은 걸지 않습니다. 사람이 읽는 한국어 산문과 모델이 읽고 실행하는 문서에 같은 규칙을 걸지 않습니다. 규칙을 고칠 때 무엇을 근거로 세웠는지 되짚을 수 있게 출처를 답니다.
작성 규칙은 config/style-rules/ 에 있습니다. 유형별 적용 대상·강도·분량 기준값·합격선은 extensions/profiles.md 가 정본입니다.
규칙별 근거 원천
| 규칙 | 근거 |
|---|---|
| 문단·목록·제목·코드 설명 | Google Developer Documentation Style Guide, Microsoft Writing Style Guide, Nielsen Norman Group 읽기 행태 연구, WCAG 1.3.1, Miller's Law |
| 번역투 판정 | 번역투 8유형 + Toury 1995(interference), Baker 1993(normalisation), Toral 2019(post-editese). 문헌 대응은 references/scholarship.md |
| AI 티 분류 골격 (A~J) | epoko77-ai/im-not-ai (MIT) 차용. K 는 자체 확장 |
| 정량 지표 14개 | 번역학 3분류로 인코딩. metrics/metrics-spec.md |
| 에이전트가 읽는 문서 | mattpocock/skills 의 writing-for-agents (MIT) 차용 |
| 쓰기 과정 단계 | 국어과 교육과정 쓰기 과정(계획·초고·퇴고). 기계 대조는 산문 린터(Vale·textlint) 계보 |
| 문서의 목적과 범위 | Barbara Minto 「The Pyramid Principle」, Google Technical Writing Course |
| 톤·구두점·분량 | 자체 작성 |
차용 원천의 채택 판본·항목 번호 대응·마지막 대조일은 references/upstream.md 가 갖습니다.
무엇을 AI 티로 보고 무엇을 저자의 취향으로 남길지는 ADR 0001 에서 정했습니다. 전부 지우면 글에서 사람이 사라집니다.
MIT. 차용 원천의 라이선스와 범위는 규칙의 근거 의 접힌 표에 있습니다.