작은 도구는 하지 않을 일로 완성됩니다

Git 정보를 보여주는 도구를 만들기 시작하면, 이상하게도 다음 기능은 늘 그럴듯합니다.

• 브랜치 전환도 있으면 좋겠고요.
• stash 적용도 있으면 좋겠고요.
• blame도 보고 싶고요.
• PR도 열고 싶고요.
• AI가 커밋 메시지도 추천하면 좋겠고요.
• 그러다 보면 GitLens도 만들 수 있지 않을까요?

아니요. 그러면 GitLens를 만들겠다는 뜻입니다. (그리고 보통 우리는 GitLens 팀이 아닙니다.)

작은 도구가 작은 이유는 기능 수가 적어서가 아닙니다. 문제를 푸는 방향이 좁기 때문입니다.

목표만 적으면 기능이 계속 자랍니다

“Source Control 화면에서 자주 보는 Git 정보를 보여준다”는 목표는 좋습니다.

하지만 목표만 있으면 모든 추가 기능이 목표와 양립해 보입니다. 브랜치 전환도 Git 정보와 관련 있고, PR도 Git과 관련 있고, AI 커밋도 어쨌든 Git과 관련 있습니다.

그래서 작은 제품에는 목표만큼이나 비목표가 필요합니다.

비목표는 두 종류로 나누면 특히 쓸모가 있습니다.

1. 이번 버전에서는 하지 않을 일: 나중에는 검토할 수 있지만 지금은 미룹니다.
2. 구조적으로 하지 않을 일: 제품의 방향을 바꾸므로 앞으로도 하지 않습니다.

이 차이를 적어두면 기능 요청을 받을 때 매번 철학 토론을 다시 열 필요가 없습니다. “좋은 제안이지만 이번 버전의 비목표입니다.”라고 말할 근거가 생깁니다.

거절문이 차가워지는 것이 아니라, 제품의 약속이 선명해집니다.

읽기 중심이라면 동사도 읽기부터입니다

상태가 있는 시스템을 다루는 도구는 처음부터 동사를 조심해야 합니다.

보기, 나열하기, 복사하기, 열기는 상태를 읽습니다. 전환하기, 적용하기, 삭제하기는 상태를 바꿉니다.

둘 다 필요할 수 있습니다. 그러나 읽기 중심 도구가 모든 변경 기능을 가져야 할 이유는 없습니다.

좋은 기준은 다음과 같습니다.

이 변경은 사용자가 자주 얻는 가치를 만들고, 안전하게 경계를 정할 수 있나요?

두 질문 모두에 예라고 답할 수 있을 때만 변경 기능을 넣습니다. 그리고 기능마다 다른 안전장치를 붙입니다.

• 작업 트리가 더러우면 branch 전환 전에 확인합니다.
• 되돌리기 어려운 작업은 항상 확인을 받습니다.
• 변경이 끝나면 읽기 화면을 새로 고쳐서, 도구가 다시 관찰자로 돌아오게 합니다.

확인창 하나를 붙였다고 안전한 도구가 되는 것은 아닙니다. 무엇을 바꿀 수 있게 할지부터 줄여야 합니다.

지원 문서도 제품의 화면입니다

Git 도구의 이슈에는 로그, 원격 URL, 패치 조각이 자연스럽게 들어옵니다. 그 말은 사용자가 비밀값, 개인 원격 주소, 액세스 토큰, 회사 코드 일부를 올릴 가능성도 높다는 뜻입니다.

“민감한 정보는 올리지 마세요”라고만 쓰면 너무 넓습니다. 사용자는 자기 상황의 URL이 민감한지, 패치가 어느 정도까지 위험한지 판단하기 어렵습니다.

대신 프로젝트가 실제로 다루는 위험물을 구체적으로 적는 편이 좋습니다.

• secrets와 access token
• private remote URL
• proprietary patch output

이 목록은 사용자를 의심하는 규칙이 아닙니다. 도구가 만들어내는 진단 정보가 무엇을 우연히 포함할 수 있는지 알려주는 안내입니다.

기능을 덜 만들수록 문장이 중요해집니다

작은 도구는 “나중에 다 넣자”는 말을 이기기 어렵습니다. 그래서 비목표를 문서로 남기고, 변경 기능을 적게 고르고, 공개 지원 경로의 위험까지 미리 적어야 합니다.

무언가를 하지 않기로 한 결정은 빈칸이 아닙니다. 사용자가 이 도구를 믿을 수 있는 이유입니다.

다음에 작은 개발 도구를 시작한다면 README의 기능 목록 아래에 한 줄을 더 적어보세요.

이 도구는 무엇을 절대 하려고 하지 않는가?

그 한 줄이 기능 스무 개보다 더 오래 제품을 지켜줄지도 모릅니다.