# Semi-structured software spec

> 상태없는 AI-인간 인터랙션을 구현하기 위한 프로세스이자 도구이자 명세서 형식. 에이전트 기반 코딩 실험 3의 결과물.

[상태없는 AI-인간 인터랙션](https://wiki.g15e.com/pages/Stateless%20AI-Human%20Interaction.txt)을 구현하기 위한 프로세스이자 도구이자 명세서 형식. [에이전트 기반 코딩 실험 3](https://wiki.g15e.com/pages/Agentic%20coding%20experiment%203.txt)의 결과물.

https://github.com/akngs/s4

## 설명

`s4`는 특정 형식을 따르는 yaml 명세서(`s4.yaml`)와 소스 코드를 정적 분석하여 다음에 해야할 일이 무엇인지를 출력하는 전통적인 CLI 프로그램이다.

`s4 status`를 실행하면

1. 명세서에 내적 일관성이 있는지(모든 비즈니스 목표에 한 개 이상의 구체적 기능이 존재하는지, 기능 사이의 의존 관계에 순환이 없는지, 모든 기능에 한 개 이상의 인수 기준이 존재하는지 등)
2. 명세서와 코드 사이가 일치하는지(명세서 상 인수 기준에 대응되는 인수 테스트가 코드에 존재하는지)
3. 명세서에 등록된 모든 검사(인수 테스트, 단위 테스트, 커버리지, 타입 검사 등)를 통과하는지를

검사한 후 문제가 발견되면 가장 먼저 해결해야할 문제가 무엇인지, 해당 문제를 해결하기 위해 필요한 뭘 하면 되는지 등을 알려준다. `s4`의 출력은 문제 해결에 필요한 맥락을 충분히 담고 있어서 [상태없는 AI-인간 인터랙션](https://wiki.g15e.com/pages/Stateless%20AI-Human%20Interaction.txt)을 가능하게 해준다.

## 부연

이 방식은 AI 에이전트가 도구의 호출 여부를 제어하고, 호출된 도구는 AI 에이전트가 잘 하지 못하는 종류의 작업을 수행한 뒤에 도구가 잘 하지 못하는 종류의 작업을 다시 AI 에이전트에게 구체적으로 지시하여 에이전트의 작업을 촉발한다는 점에서 [재귀적 신경기호 제어 역전](https://wiki.g15e.com/pages/Recursive%20Neuro-Symbloic%20Inversion%20of%20Control.txt) 패턴의 일종이라고 볼 수 있다.

## 개선점

- [Alloy](https://wiki.g15e.com/pages/Alloy%20Analyzer.txt) 등을 이용한 형식화
  - 어쩌면 반자동으로? 예: 명세를 자연어로 적으면 AI가 Alloy 모델을 만들어준다. 모호성이 있는 부분에 대해 예시를 여러개 보여주며 어떤 게 의도에 부합하는지 사용자에게 물어보고 이를 통해 스펙을 정교하게 다듬기
  - [자연어로 작성된 명세서](https://wiki.g15e.com/pages/Specification%20written%20in%20natural%20language.txt)
  - [Model-driven testing](https://wiki.g15e.com/pages/Model-driven%20testing.txt)
- [MCP](https://wiki.g15e.com/pages/Model%20context%20protocol.txt)와 유사한 프롬프트 템플릿. 예:
  - 명세서의 AT와 코드로 구현된 AT가 의미적으로 일치하는지 검사
  - 명세서의 서로 다른 두 기능이 의미적으로 동일한지 검사
  - 명세서의 서로 다른 두 인수 테스트가 의미적으로 동일한지 검사
- Forward engineering vs. reverse engineering. 레거시 프로젝트에 이 방법론을 적용하려면 reverse 모드로. 새로 시작하는 프로젝트에서는 forward 모드로. Forward 모드에서는 명세서가 <Single source of truth>라면 reverse 모드에서는 코드가 SSoT인 상태에서 점진적으로 권위(?)를 명세서로 옮겨오는 방식.
- <깃>과 연결하기. 비싼(시간이 오래 걸리거나 토큰을 많이 쓰거나 등) 작업은 바뀐 코드에 대해서만 적용
- 의존성 그래프: 예를 들어 특정 기능을 선택하면 해당 기능이 의존하는 다른 기능, 해당 기능에 의존하는 다른 기능, 해당 기능과 연결된 인수 테스트 등을 LLM이 읽기 쉽도록 보여주기
- 스펙 리팩토링을 도와줄 무언가. 리팩토링이란?
  - 하나의 FEAT을 둘로 나누기
  - 두개의 FEAT을 하나로 합치기
  - …