새로운 기능을 시작할 때마다 저는 똑같은 과정을 반복했습니다. 빈 문서를 엽니다. 제대로 된 기술 명세서 (technical spec)에 어떤 섹션들이 필요한지 기억해내려 애씁니다. 이전 프로젝트에서 사용했던 오래된 ADR 템플릿을 복사한 뒤 해당하지 않는 부분들을 제거합니다. 작업 중간쯤에 롤백 단계 (rollback steps)나 액세스 제어 (access control), 혹은 새벽 3시에 무언가 실패했을 때 어떤 일이 벌어질지에 대해 생각하는 것을 잊었다는 사실을 깨닫습니다.

이 중 어떤 것도 힘든 작업은 아닙니다. 그저 반복적일 뿐이며, 반복적인 작업은 급할 때 정확히 생략되기 쉬운 종류의 일입니다. 그리고 이를 생략하는 과정에서 위협 모델 (threat model)도 없고, 롤백 계획 (rollback plan)도 없으며, 6개월 후에 팀원 중 누구도 왜 그런 결정이 내려졌는지 확신하지 못하는 상태로 기능을 출시하게 됩니다.

그래서 저는 engineering-docs를 만들었습니다. 이것은 초기 단계의 모호한 아이디어부터 운영 환경 (production)에서 무언가 고장 난 후의 사후 분석 (postmortem)에 이르기까지, 소프트웨어 작성의 전체 라이프사이클 (lifecycle)을 다루는 코딩 에이전트 (coding agents)를 위한 21개의 스킬 세트입니다.

제가 실제로 해결하려 했던 문제

저는 OwnPay(셀프 호스팅 결제 게이트웨이)와 몇 가지 보안 도구와 같이 여러 프로젝트를 동시에 수행합니다. 그 모든 프로젝트에는 동일한 종류의 문서화가 필요합니다. 구축 전의 명세서 (spec). 시스템의 형태가 명확해진 후의 아키텍처 문서 (architecture doc). 돈이나 사용자 데이터에 관여하기 전의 위협 모델 (threat model). 운영 환경 (production)에 배포하기 전의 배포 계획 (deployment plan). 그리고 무언가 잘못되었을 때의 사후 분석 (postmortem)인데, 왜냐하면 결국에는 항상 무언가 잘못되기 마련이기 때문입니다.

저는 이 모든 것들을 어떻게 작성하는지 알고 있습니다. 그것은 결코 문제가 아니었습니다. 문제는 제가 피곤하거나 마감 기한이 임박했다는 이유로 요령을 피우지 않고, 매번 일관되게 이를 수행하는 것이었습니다. 그리고 제가 일상 업무에 AI 코딩 에이전트 (AI coding agents)를 더 많이 의존하기 시작했을 때, 그들도 저와 정확히 똑같은 문제를 겪고 있다는 것을 깨달았습니다. 에이전트에게 "이 기능을 위한 데이터베이스를 설계해줘"라고 요청하면, 인덱싱 전략 (indexing strategy), 마이그레이션 롤백 (migration rollback), 또는 특정 정규화 (normalization) 선택이 왜 이루어졌는지에 대한 고민 없이 몇 개의 CREATE TABLE 문만 받는 경우가 대부분입니다. API 초안을 작성해달라고 요청하면 에러 계약 (error contract), 버전 관리 전략 (versioning strategy), 속도 제한 (rate limiting)에 대한 내용이 전혀 없는 엔드포인트(endpoints)를 받게 됩니다.

에이전트가 게으른 것이 아닙니다. 단지 실제 시스템 아키텍처 문서 (system architecture document)가 특정한 형태를 가지고 있다는 것, 혹은 좋은 위협 모델 (threat model)이 STRIDE를 따른다는 것, 또는 적절한 API 설계가 리처드슨 성숙도 모델 (Richardson Maturity Model)을 참조한다는 것을 알지 못할 뿐입니다. 그러한 지식은 그것을 가르친 사람의 머릿속에 들어있으며, 대부분의 경우 아무도 그것에게 아무것도 가르치지 않았습니다. 그것은 그저 학습 데이터 (training data)에서 흔히 발견되는 미완성된 사양 (specs)들에 대해 패턴 매칭 (pattern matching)을 하고 있을 뿐입니다.

따라서 해결책은 "매번 더 나은 프롬프트 (prompts)를 작성하는 것"이 아니었습니다. 해결책은 주니어 엔지니어가 시니어 엔지니어로부터 충분히 좋은 사례들을 본 후에 결국 형식을 내면화하는 것과 같은 방식으로, 좋은 엔지니어링 문서화 (engineering documentation)의 실제 구조를 에이전트가 자동으로 불러와서 따를 수 있는 무언가로 인코딩(encode)하는 것이었습니다.

실제로 무엇이 들어있는가

이 저장소 (repo)에는 21개의 스킬 (skills)이 있으며, 이는 실제 프로젝트가 아이디어에서 프로덕션 (production)으로 넘어가는 과정과 대략적으로 일치하는 다섯 가지 단계로 그룹화되어 있습니다.

탐색 및 계획 (Discovery and planning). 이것은 대략적인 아이디어만 있을 때 시작하는 단계입니다. 모든 템플릿에 등장하는 일반적인 "32세, 바쁜 직장인 사라"와 같은 자리 채우기용 페르소나가 아니라, 실제 수행해야 할 과업 (jobs-to-be-done)과 성공 지표 (success metrics)를 포함한 사용자 페르소나 (user personas)를 구축하는 스킬이 있습니다. 또한 마일스톤 (milestones), RACI 매트릭스 (RACI matrix), 그리고 작업 분할 구조 (work breakdown structure)를 위한 프로젝트 계획 스킬도 있습니다.

사양 및 타당성 (Specification and feasibility). 누군가 코드를 작성하기 전에, ISO/IEC/IEEE 29148을 따르는 적절한 소프트웨어 요구사항 명세서 (Software Requirements Specification)를 생성하는 스킬이 있습니다. 이때 실제 요구사항에는 EARS 구문을 사용합니다. 또한 타당성 조사 (feasibility study) 스킬도 있어, 리소스를 투입하기 전에 아이디어가 현실적인지 제정신인지 확인 (sanity check)할 수 있습니다.

아키텍처 및 제품 설계 (Architecture and product design). 이것은 가장 큰 그룹이며, 저에게 있어 일상적인 가치가 가장 많이 나타나는 부분입니다. C4 모델을 사용한 시스템 아키텍처 (System architecture). 실제 ERD (Entity Relationship Diagram)와 인덱스 및 캐스케이드 규칙 (cascade rules)까지 포함된 적절한 데이터 사전 (data dictionary)을 갖춘 데이터베이스 설계. 임의로 만든 에러 형태 대신 RFC 7807 에러 핸들링을 적용하여 OpenAPI 3.1에 맞춘 API 설계. 아키텍처 결정 기록 (Architecture Decision Records, ADR)은 ADR이 작성되어야 하는 방식대로 작성됩니다. 즉, 승인되면 변경 불가능하며, 단순히 최종 결정만 적는 것이 아니라 대안과 트레이드오프 (trade-offs)를 실제로 상세히 기술합니다.

리스크 및 품질 (Risk and quality). STRIDE와 OWASP를 사용하는 위협 모델링 (threat model) 스킬이 있는데, 이는 보안 감사 (security audit) 중에나 겨우 발견했을 보안 격차를 미리 잡아내는 역할을 합니다. 테스트 전략 (test strategy) 문서. 단순히 작업 목록을 나열하는 대신 의존성 (dependency)에 따라 작업 순서를 정하는 구현 계획 (implementation plan).

배포 및 운영 (Deployment and operations). 단순히 "금요일에 배포하고 기도하기"가 아니라, 명시적인 진행 (go) 및 중단 (no-go) 게이트가 포함된 배포 계획. SLO (Service Level Objective) 및 에러 예산 (error budget) 문서. 알람에서 진단, 에스컬레이션 (escalation)까지 연결하는 Google의 SRE 팀이 사용하는 형식의 런북 (Runbooks). 실제 RTO (Recovery Time Objective) 및 RPO (Recovery Point Objective) 목표를 포함한 재해 복구 (disaster recovery) 계획. 그리고 5 Whys 기법을 사용하는 비난 없는 사후 분석 (blameless postmortem) 스킬입니다. 사후 분석의 목적은 누군가를 비난할 대상을 찾는 것이 아니라 시스템을 고치는 것이기 때문입니다.

이 모든 것의 상위 계층에는 using-engineering-docs라고 불리는 오케스트레이터 (orchestrator) 스킬이 있습니다. 당신이 가공되지 않은 아이디어를 설명하면, 이 스킬은 몇 가지 타겟팅된 질문으로 당신을 인터뷰하고, 21개의 스킬 중 실제로 어떤 것들이 적용되는지 파악하여 적절한 순서로 배치합니다. 당신은 어떤 스킬을 사용해야 할지 기억할 필요가 없습니다. 대화를 통해 시스템이 스스로 찾아내기 때문입니다.

아무것도 작성하기 전에 인터뷰를 하는 이유

이 부분은 들리는 것보다 훨씬 더 중요합니다. 스킬들은 당신이 요청하자마자 바로 문서를 생성하지 않습니다. 대신, 유능한 시니어 엔지니어가 코드를 작성하기 전에 모호한 티켓 (ticket)에 대해 이의를 제기하는 것과 같은 방식으로, 먼저 3~5개의 명확화 질문 (clarifying questions)을 던집니다.

만약 당신이 데이터베이스 설계 (database design)를 요청했는데 예상되는 읽기 및 쓰기 볼륨 (read and write volume)에 대해 아무것도 말하지 않았다면, 시스템은 이를 질문합니다. API 설계 (API design)를 요청하면서 연결이 불안정한 모바일 클라이언트를 지원해야 하는지 언급하지 않았다면, 역시 질문을 던집니다. 질문을 통해서도 해결할 수 없는 진정한 공백이 있을 때는, 지어낸 답변을 내놓는 대신 문서에 명시적인 마커 (marker)를 남깁니다. 가정 사항은 🔶로, 미결 질문은 🔵로 문서 내에 직접 표시되므로, 나중에 문서를 읽는 사람은 어떤 부분이 확인되었고 어떤 부분이 여전히 결정이 필요한지 정확히 알 수 있습니다.

AI가 생성한 문서들이 실제로는 조용하고 명시되지 않은 가정들로 가득 차 있으면서도, 마치 자신감 있고 완벽한 것처럼 읽히는 경우가 얼마나 빈번한지 깨닫고 이 기능을 추가했습니다. 모든 답을 알고 있는 척하는 문서보다, 아직 모르는 부분을 솔직하게 표시하는 문서가 훨씬 더 안전합니다.

실행 방법

직접 시도해보고 싶다면, 가장 빠른 방법은 다음과 같습니다:

npx engineering-docs

이 도구는 사용자의 환경을 감지하고 어떤 에이전트 하네스 (agent harness)를 사용 중인지 묻습니다. 현재는 Claude Code, Cursor 및 Windsurf, Kimi Code, Codex 및 GitHub Copilot, 그리고 Antigravity를 통한 Gemini를 지원합니다. Cursor는 .mdc 규칙 파일을 기대하고 Claude Code는 플러그인 구조를 기대하기 때문에 각 에이전트마다 고유한 매니페스트 (manifest) 형식을 갖지만, 사용자가 시작할 때 이 모든 것을 미리 알 필요는 없습니다.

특히 Claude Code의 경우, 다음과 같이 플러그인 마켓플레이스 (plugin marketplace)에 직접 등록할 수도 있습니다:

/plugin marketplace add fattain-naime/engineering-docs
/plugin install engineering-docs@engineering-docs

만약 npx를 완전히 건너뛰고 무엇이 어디로 복사되는지 정확히 확인하고 싶다면, 저장소(repo)에 일반 셸 (shell) 및 PowerShell 스크립트도 포함되어 있습니다.

제가 주의를 기울인 작은 점 하나는 다음과 같습니다: 설치 과정에서 이미 AGENTS.md, GEMINI.md, 또는 CLAUDE.md 파일이 있다면 절대 덮어쓰지 않습니다. 대상 위치에 해당 파일들이 이미 존재한다면, 설치 프로그램은 해당 파일들을 건너뛰고 그 사실을 로그에 기록합니다. 전역 설치 명령어가 누군가의 기존 에이전트 설정을 조용히 지워버리는 상황을 원치 않았기 때문입니다.

하나의 거대한 프롬프트 대신 스킬 (skills)을 사용하는 이유

저는 모든 종류의 문서를 다루려고 시도하는 하나의 긴 시스템 프롬프트 (system prompt)로 이 도구를 작성할 수도 있었습니다. 실제로 처음에는 그렇게 시도해 보았지만, 결과가 좋지 않았습니다. ADR (Architecture Decision Record), 데이터베이스 설계 문서, 그리고 장애 사후 분석 (incident postmortem) 형식을 한꺼번에 유지하려고 하는 단일 프롬프트는, 유용할 정도로 구체적이지 못하거나 너무 길어져서 에이전트가 일부 내용을 무시하기 시작합니다.

사용자가 실제로 요청하는 내용에 따라 자동으로 트리거되는 21개의 별개이고 집중된 스킬 (skills)로 나누면 각 스킬의 날카로움을 유지할 수 있습니다. 데이터베이스 설계 스킬은 데이터베이스 설계만 잘하면 됩니다. 재해 복구 계획 (disaster recovery plan)의 형식까지 알 필요는 없습니다. 또한 이들은 조합 가능 (composable)하기 때문에, 오케스트레이터 (orchestrator) 스킬은 모든 프로젝트에 동일한 고정 체크리스트를 강요하는 대신 특정 프로젝트에 정확히 필요한 스킬들만 가져올 수 있습니다.

여전히 추가하고 싶은 것들

스킬 라이브러리는 아직 완성되지 않았으며, "완성되었다"는 의미에서 결코 완전히 끝날 것이라고 생각하지도 않습니다. 소프트웨어 엔지니어링 (Software engineering) 관행은 계속해서 진화하고 있기 때문입니다. 다음에 확장하고 싶은 몇 가지 영역은 데이터 파이프라인 (Data pipeline) 및 ETL 설계에 대한 더 깊은 내용, 그리고 레거시 인프라 (Legacy infrastructure)에서 벗어날 때 필요한 마이그레이션 계획 (Migration planning)을 위한 전용 스킬입니다. 마이그레이션은 여전히 오래된 공유 호스팅 (Shared hosting) 설정을 사용하는 고객들과 작업할 때 제가 끊임없이 마주하는 문제입니다.

직접 사용해 보다가 공백을 발견하거나, 숙련된 시니어 엔지니어 (Senior engineer)라면 물어볼 법한 내용이 스킬에 빠져 있다고 생각된다면, 이슈 (Issue)를 생성하거나 PR (Pull Request)을 보내주세요. 기여 가이드 (Contributing guide)에는 YAML 프론트매터 (YAML frontmatter)와 코칭 블록 (Coaching blocks)이 어떻게 구조화되어 있는지 설명되어 있으므로, 새로운 스킬을 추가하는 것은 처음부터 역공학 (Reverse engineering)을 하는 것이 아니라 기존 패턴을 따르는 문제에 가깝습니다.

• Repository: github.com/fattain-naime/engineering-docs
• License: MIT

만약 기능을 배포하고 3주 뒤에야 어떤 결정이 왜 내려졌는지 아무도 기록해두지 않았다는 사실을 깨달은 적이 있다면, 이 라이브러리가 그런 일을 다시 겪지 않도록 도와줄 것입니다.