SpecMD — 당신의 문서가 코드라면?

Source: Dev.to

The Problem

소프트웨어 개발에서 가장 큰 고통 중 하나는 문서와 코드를 동기화하는 일입니다.

문서는 종종:

• 오래됨
• 무시됨
• 실제 코드와 일관되지 않음
• 유지보수가 어려움
• 거의 신뢰받지 못함

반면에 코드는:

• 진실의 출처
• 신뢰할 수 있음
• 즉시 이해하기 어려움

이 두 세계가 반드시 분리될 필요는 없습니다.

The SpecMD Approach

SpecMD는 문서를 Markdown으로 작성하고, 그 Markdown이 소프트웨어가 어떻게 동작해야 하는지에 대한 진실의 출처가 되는 접근 방식입니다.

Core Idea

1. 의도된 동작과 규칙을 평문으로 작성합니다.
2. 그 텍스트가 실행 가능한 코드가 됩니다.
3. 코드는 구현이 문서와 일치하는지 검증합니다.

문서와 구현이 어긋나면:

• 테스트가 실패합니다.
• 불일치가 즉시 드러납니다.

How It Works

• 문서의 한 줄이 이렇게 말할 수 있습니다: “사용자의 이메일 주소는 시스템 내에서 고유해야 합니다.”
• 그 문장은 실행 가능한 로직이 됩니다.
• 구현이 중복을 허용한다면, 문서가 오류를 표면화합니다.

이렇게 문서는 강제 수단이 됩니다.

Benefits

SpecMD는 다음과 같은 팀에 도움이 될 수 있습니다:

• 중요한 시스템을 구축하는 팀
• 규모가 크거나 분산된 코드베이스를 관리하는 팀
• 신규 개발자를 자주 온보딩하는 팀
• 복잡한 비즈니스 규칙을 유지하는 팀
• 신뢰할 수 있는 문서가 필요한 팀
• 명확성과 추적성을 원하는 팀

오래된 문서 때문에 고생한 적이 있다면, 이 내용이 공감될 것입니다.

Further Reading

• 전체 글:
• GitHub Open Research Project:

Discussion

• 문서가 소프트웨어를 구축하는 방식에 더 적극적인 역할을 해야 할까요?
• 설명이 실행이 될 수 있을까요?

생각을 남겨 주세요 — 이 문제와 싸워온 다른 개발자들의 관점을 듣고 싶습니다.