정적 포트폴리오에서 인덱스 기반 의사결정으로 📃

Source: Dev.to

이 글은 Algolia Agent Studio Challenge: Consumer‑Facing Non‑Conversational Experiences 에 대한 제출물입니다

🦄 New Year, New You 구글 챌린지와 함께 이 과제를 보자마자 바로 만들 무언가가 떠올랐어요. 솔직히 말해서, 포트폴리오를 만들고 싶었지만 오랫동안 우선순위에 두지 못했었거든요. 이번 챌린지가 그 아이디어를 실제로 실행에 옮길 만큼 충분히 흥미로웠습니다.

게다가 이야기가 붙어 있으면 왜 작동하는지를 보여주는 것이 훨씬 더 만족스럽죠. 빨리 보고 싶다면 최소한 첫 번째 부분은 꼼꼼히 읽어 주세요.

정적 포트폴리오는 결정을 서사로 다룹니다. 이 프로젝트는 결정을 데이터로 다룹니다.

내가 만든 것

이 백엔드‑중심 프로젝트는 예쁜 UI를 위해 만든 것이 아니라 시스템을 위해 만든 것이다. 나는 비대화형 포트폴리오를 만들었으며, 이는 정적인 전시가 아니라 잘 윤활된 기계처럼 동작한다.

전통적인 포트폴리오는 해석이 필요하다. 이 시스템은 해석을 완전히 없앤다.

포트폴리오 사이트를 처음 구상했을 때, 나는 일반적인 LinkedIn 이력서와는 차별화되길 원했다. 나는 최선의 날에도 “보통”이라는 것에 강한 알레르기가 있지만, 새로움만으로는 확장되지 않는다. 또한 시간이 지나도 끊임없는 실험과 접근 방식 변화에 견딜 수 있는 충분히 강력한 인프라가 필요하다는 것도 알았다.

당연히, 이러한 생각들은 하나의 결정으로 수렴되었다: 프로젝트, 고민, 그리고 결정들을 실시간으로 기록하는 살아있는 일지를 만든다.

결정은 여기서 일급 기록이며, 설명적인 산문이 아니다.

미래의 내가 몇 달 후에 “도대체 무슨 생각을 했던 걸까?” 라고 물을 때, 이를 조회할 수 있게 하기 위함이다.

이 챌린지 포스트를 보자마자, 나는 모든 도전, 결정, 결과, 제약을 문서화하기 시작했다. 그 과정은 기존 GitHub 프로젝트에서 재구성할 수 있는 모든 것부터 시작했다.

🦄 내가 마음을 바꾼 모든 순간을 문서화했더라도, 이 인덱스 구조는 충분히 감당할 수 있다. 걱정 마라—그 정도까지는 하지 않았다.

인덱스 설계

인덱스는 시스템 그 자체입니다. 인덱스가 실패하면 다른 모든 것은 의미가 없습니다.

UI 측에서 어시스턴트 에이전트를 제어하는 방법을 잡은 뒤, 인덱스가 실제 작업이 되었습니다. 인덱스를 설계하고, 깨뜨리고, 정제하는 데 가장 많은 시간이 들었습니다. 초기 패턴은 검색 성능이 좋지 않았지만, Algolia 베스트 프랙티스 가이드를 공부한 뒤에야 비로소 이해가 되었습니다.

그 결과는 검색에 최적화된 작고 원자적인 레코드들의 모음입니다.

이 레코드들은 신호 강도와 레코드 생성 시간을 모두 활용한 결정적 정렬과 파싯을 통해 깔끔한 UX를 제공합니다.

다음은 사이트에서 직접 가져온 실제 예시입니다:

[
  {
    "objectID": "card:project:challenge:algolia-agent-studio-2026-02",
    "title": "Algolia Agent Studio Challenge participation",
    "blurb": "An applied exploration of conversational retrieval.",
    "fact": "I participated in the Algolia Agent Studio DEV Challenge during February 2026, focusing on conversational and non‑conversational search behavior using indexed content.",
    "tags.lvl0": ["DEV Challenge", "Approach"],
    "tags.lvl1": [
      "DEV Challenge > Algolia Agent Studio",
      "Approach > Experimentation"
    ],
    "projects": ["System Notes"],
    "category": "Experience",
    "created_at": "2026-02-08T05:42:00-05:00",
    "signal": 5
  }
]

왜 이러한 필드가 존재하는가

• signal – 순위 매김 시 관련성 압력을 제어합니다.
• created_at – 시간에 따라 정렬을 안정화합니다.
• 계층형 태그 – 희석 없이 범위를 좁히게 해줍니다.
• 제한된 카테고리 – 모호한 그룹화를 방지합니다.

🦄 혹시 궁금하실까봐 말씀드리자면, 이 레코드들을 손으로 직접 작성한 것은 아닙니다. 규칙과 제약을 정의하고 이를 ChatGPT에 전달했으며, 생성된 결과물을 System Notes v2.0.0/Algolia 저장소에 있는 JSON 파일에 수동으로 기록했습니다.

Source: …

AI에게 물어보기 검색

이 프로젝트에는 대화형 채팅 인터페이스와 Ask AI 검색 경험이 모두 포함되어 있습니다.

이번 항목에서는 Ask AI를 순수 검색 인터페이스로만 취급하고, 대화형 에이전트로 사용하지 않습니다.

대화 상태는 선택 사항이며, 여기서는 Algolia 인덱스에 대해 실행된 비대화형 쿼리만을 고려한 결과를 보여줍니다.

시간에 따라 검색 성능을 평가했습니다—특히 속도, 관련성, 일관성을 측정하고 인덱스 구성, 랭킹 규칙, 그리고 파싯을 반복적으로 개선했습니다.

동일한 쿼리가 동일한 결과를 반환하지 않는다면, 구성은 아직 완료되지 않은 것입니다.

시스템은 이제 쿼리 재작성 없이도 올바른 인덱스 레코드를 빠르고 예측 가능하게 반환합니다.

실시간 데모

사이트는 이전 챌린지 제출과 구분하기 위해 에 배포되었습니다.

“Algolia”를 검색하거나 왼쪽의 카테고리로 필터링하여 관련 결과를 로드해 보세요.

현재 정식 버전:

소스 코드: System Notes v2.0.0

🦄 전체 비교 스냅샷을 원한다면 원본 사이트가 에 여전히 라이브 상태입니다. 해당 버전과 Algolia 기반 빌드 간의 차이는 극명합니다.

Algolia Agent Studio in Practice

잘 설계된 인덱스만으로는 충분하지 않습니다.

검색 품질은 기능 수가 아니라 구성 규율에 의해 결정됩니다.

시스템을 튜닝하면서 Algolia 구성 패널에서 제공되는 대부분의 옵션을 테스트했습니다. 가장 큰 영향을 미친 변경 사항은 검색 가능한 속성을 적극적으로 제한하고 퍼싯 정의를 강화하는 것이었습니다.

또한, 지나치게 관대한 동의어 확장은 에이전트 검색 속도에 부정적인 영향을 미치는 것을 발견했으며, 따라서 이를 의도적으로 축소했습니다.

인덱스를 동기화 유지하기

수동으로 콘텐츠를 복제하는 것을 방지하기 위해, AI‑최적화된 미러 사이트를 사용해 DEV의 콘텐츠를 색인하도록 Algolia 크롤러를 설정했습니다.

이렇게 하면 사람의 개입 없이 인덱스가 권위 있게 유지됩니다.

크롤러는 Algolia 대시보드에서 직접 관리되는 가벼운 JavaScript 구성 파일입니다.

💡 크롤러 구성 파일은 레포지토리의
apps/api/algolia/sources/crawler.js (System Notes v2.0.0)
에 저장되어 있습니다.

분석을 활용한 튜닝

불행하게도 API‑key 실수 때문에 전체 과거 분석 데이터를 보관하지 못했습니다.

그럼에도 불구하고, 분석을 사용해 반복 쿼리 시 검색 동작이 안정화되었음을 확인했습니다.

🦄 참고로, Algolia는 원래 키를 기록해 두면 API‑key 복구가 매우 간편합니다. 물론 저는 기록하지 않았죠.

Source: …

왜 빠르고 예측 가능한 검색이 중요한가

Algolia 이전에는 사용자가 프로젝트와 연결된 모든 의미 있는 결정을 기억하고 문서화하기 위해 저에게 의존해야 했습니다.

그것은 확장되지 않는다. 검색은 확장된다.

이제 저는 활성 빌드 전반에 걸쳐 수백 개의 결정‑레벨 레코드를 신속하게 검색할 수 있는 시스템을 갖추게 되었습니다.

이 시스템은 Algolia 없이는 존재할 수 없었습니다. 이것은 개선이 아니라 기반입니다.

다음 단계

시간이 부족했고 이 챌린지는 강제 종료되었습니다.

선택이 주어진다면, 나는 기능 폭보다 검색 안정성을 최적화했습니다.

시간이 허락한다면, 다음 단계가 있습니다:

• 검색 결과를 직접 주소 지정할 수 있도록 맞춤 URL 라우팅을 구현합니다
• 실제 사용자 상호작용 이벤트에 기반한 추천을 최종 확정합니다
• 장기 성장을 지원하기 위해 인덱스된 레코드용 Supabase 백업 스토어를 도입합니다
• 기존 프로젝트 카드를 새로운 인덱스 레코드 형식으로 마이그레이션합니다
• UI 정제와 성능 튜닝을 지속합니다

🦄 수상자가 발표된 후, 이 사이트는 제 포트폴리오의 공식 주소인 에만 존재하게 됩니다.

🛡️ 여백 속의 공로

이 글은 인간이 작성했으며, 초안 작성 과정에서 편집, 명확성 검토, 구조적 다듬기를 위해 ChatGPT를 활용했습니다. 최종 형태, 기술적 주장 및 결정은 인간이 만든 것입니다.