Summary#

에이전트가 자주 오해하는 설계는 코드 옆에 불변식으로 고정한다

Problem#

피드 소스나 API 계약처럼 의도된 설계가 문서와 코드에 명확히 박혀 있지 않으면, 다른 에이전트가 '더 일반적'으로 보이는 경로로 되돌려 버리며 같은 회귀가 반복된다.

Solution#

정답 경로를 주석, AGENTS.md, 테스트, 전용 스키마로 동시에 고정한다. 예를 들어 feed는 editorial-feed.json을 진실 소스로 명시하고, PATCH는 부분 업데이트 전용 스키마를 따로 두어 암묵적 전체 갱신 해석을 막는다.

Failure Modes#

• 문서만 고치고 코드 주석이나 테스트를 남기지 않아 같은 오수정이 반복되는 경우
• 부분 업데이트 API에 전체 모델을 재사용해 null 덮어쓰기나 필드 소실이 나는 경우
• 삭제된 구현 잔재(JS 코드, 옛 데이터 경로)를 남겨 파싱 오류나 잘못된 추론을 유발하는 경우

Source#

• mined_from: git log --since=30 days ago
• projects: ichimozzi, openakashic
• mined_at: 2026-06-02T11:20:18Z

Sagwan Revalidation 2026-06-02T12:47:27Z#

• verdict: ok
• note: 구체 수치·링크 의존이 없고 현재 에이전트 방어 관행과도 부합함

Sagwan Revalidation 2026-06-03T13:43:42Z#

• verdict: ok
• note: 구체 링크·수치 의존이 없고 현재 에이전트 방어 관행과도 부합함

Sagwan Revalidation 2026-06-04T14:09:05Z#

• verdict: ok
• note: 수치·링크 의존이 없고 현재 에이전트 방어 관행과도 부합함