시작하기

당신의 AI는 눈먼 채로 코딩하고 있습니다

세션이 끝나면 구조를 잊고, 정책을 모르고, 뭘 깨뜨리는지도 모릅니다.

매 세션마다 당신의 AI는:

  • 파일 위치를 find/grep으로 헤매다 토큰의 20–30%를 소모하고
  • 비즈니스 정책(회원 등급별 제한, 탈퇴 유예 기간, 외부 API 호출 한도 등)은 코드만 봐선 알 수 없고
  • "이 기능을 고치면 어디가 깨지는지" 판단할 데이터가 없어서 조용히 터지는 코드를 만듭니다.

    • README 한 장으론 이걸 못 채웁니다. Fluct를 연결하면 AI가 눈을 뜹니다.

    ---

    ## Fluct가 제공하는 것

    1. 구조화된 서비스 메모리

    제품·페이지·기능을 노드로 기록하고, 각 노드에 AI가 직접 채우는 메타데이터를 붙입니다:

  • sourceFiles / testFiles — 이 노드를 구현하는 파일 경로 (AI가 바로 열기)
  • ioContract — inputs / outputs / errors / sideEffects 4종 명시
  • stateTouches — 이 노드가 읽거나 쓰는 DB 테이블, 외부 API
  • runtimeContext — 파일만 봐선 안 보이는 cron·edge·webhook·큐 같은 런타임 사실
  • acceptanceCriteria — 테스트 에이전트가 기계적으로 verify할 "완료 체크리스트"
  • policy — 코드에 enforce되는 비즈니스 규칙

    • 맵 자체에도 envFiles·configFiles·notes를 저장해서, AI가 레포에 들어올 때 먼저 봐야 하는 진입점을 한 번에 받습니다.

    2. 의존성 그래프 + 영향도 전파 (킬러 기능)

    4종 엣지(product/page/feature/page_feature)로 노드 간 연결을 그립니다. 파괴적 변경 전 AI가 analyze_impact를 부르면:

  • Direct state touches — 이 노드가 직접 건드리는 테이블/서비스
  • viaOutgoingDeps — outgoing 이웃이 건드리는 state (간접 영향 반경)
  • viaIncomingCallers — incoming caller가 이 노드를 어떤 state 맥락에서 쓰는지
  • 참조 시나리오 스텝 + 앵커 연결 — 고아가 될 유저 플로우
  • changeKind별 Risks — delete/rescope/rename 시 터질 포인트

    • 텍스트 문서(README/마크다운)로는 원천 불가능한, AI-native 메모리의 증거입니다.

    3. 1-호출 수정 컨텍스트 번들 (`get_node_context`)

    단일 노드를 수정할 땐 전체 맵을 받을 필요가 없습니다. search_nodes로 키워드 검색(결과에 sourceFiles 2개 미리보기 포함) → get_node_context(nodeId) 한 번으로 노드 본체 + 부모 체인 + 의존성 + transitive state + 미해결 blocker/known-issue 댓글 + 맵 전역 aiContext가 구조화된 JSON으로 나옵니다. 4–5 round-trip이 1 호출로 줄어듭니다.

    4. 블로커 / 알려진 이슈 / 핸드오프 라벨

    댓글에 blocker(현재 작업을 막는 이슈) / known_issue(알려진 버그 — "고쳐야 할 것"으로 오인 금지) / handoff(다음 에이전트에게 넘기는 쪽지) 태그. AI가 수정 전 반드시 확인하므로 "이미 알려진 버그를 또 고쳐버리는" 낭비가 사라지고, planning → dev → prd 상태 전환 시 에이전트 간 인수인계가 자동화됩니다.

    5. 라이브 에이전트 뷰 (wow 레이어)

    AI가 MCP로 맵을 건드리는 동안 화이트보드에 실시간으로 보입니다: 🤖 유령 커서가 노드 사이를 glide, 건드린 노드는 펄스 glow (sky=read / emerald=write / amber=impact), 우상단에 툴 호출 피드 스트리밍. "내 AI가 지금 내 맵 위에서 일하고 있다"는 감각이 즉시 와닿습니다.

    6. 시각적 협업 + 유저 시나리오 + 버전 비교

    사람을 위한 화이트보드 캔버스, 프로젝트 기반 워크플로우, 유저 플로우 시나리오(앵커로 분기 연결), 스냅샷 기반 side-by-side diff, 권한 라벨. PM이 기획을 맵에 쓰면 AI가 바로 구현합니다.

    ---

    ## 누가 쓰면 좋은가

  • 바이브 코더 — AI로 빠르게 만들지만 커지면 두려워지는 1인·소규모 팀
  • 기획 기반 팀 — PM이 서비스맵에 기획을 쓰면 개발자가 AI와 그대로 구현
  • AI 코딩 에이전트를 적극 쓰는 팀 — README 한 장으론 안 되는 구조·정책·영향도·런타임 사실을 1급 객체로 가져가는 팀

    • README는 사람을 위한 한 장짜리 요약이고, Fluct는 AI에게 눈을 달아주는 구조화 메모리입니다.