해피 테크로그

AI에게 일을 맡겼는데 첫 답은 그럴듯하지만 프로젝트의 규칙을 놓치거나, 매번 같은 설명을 반복하게 되는 일이 있다. 모델이 충분히 똑똑하지 않아서만은 아니다. 대개는 Context(맥락) 가 흐릿하기 때문이다. Context는 AI에게 주는 ‘작업 설명서와 현장 지도’다. 지도 없이 “맛집 찾아줘”라고 하면 유명한 곳만 말하지만, 동네·예산·인원·알레르기를 알려주면 현실적인 선택을 한다. 코딩 에이전트도 같다. 핵심 한 줄 좋은 Context는 많이 넣은 정보가 아니라, 이번 판단에 필요한 사실을 정확한 위치에 둔 정보 다. 1. 작업 목표와 ‘완료’를 함께 적는다 “로그인 기능 만들어줘”는 출발점일 뿐이다. 어떤 화면에서, 무엇을 허용하고, 테스트가 통과하면 끝인지가 있어야 AI도 같은 결승선을 본다. 나쁜 요청 좋은 요청 로그인 만들어줘 Next.js 앱에 이메일 로그인 화면을 추가해줘. 기존 디자인 토큰을 쓰고, 로그인 실패 문구는 한국어로 표시해줘. npm test 와 npm run lint 가 통과하면 완료야. 2. 변하지 않는 규칙은 파일로, 오늘의 일은 대화로 매번 말해야 하는 규칙은 대화창이 아니라 저장소의 AGENTS.md 에 둔다. Codex 공식 가이드는 이 파일에 프로젝트 구조, 실행·빌드·테스트 명령, 코딩 관례, 금지 사항, 완료 기준을 담으라고 권한다. 특히 짧고 정확한 파일이 길고 모호한 파일보다 낫다 고 설명한다. OpenAI Codex Manual Claude Code에서는 같은 역할을 CLAUDE.md 가 맡는다. Claude의 공식 문서도 “매 세션마다 다시 설명할 사실”만 적고, 반복 실수가 두 번째 생길 때 추가하라고 권한다. 구체적이고 간결하게 쓸수록 잘 지켜진다. Claude Code 문서 # AGENTS.md - 패키지 매니저는 pnpm만 사용한다. - 변경 전 관련 테스트를 먼저 찾는다. - API 응답 형식 변경 시 OpenAPI 스키마와 테스트를 함께 수정한다. - 완료 전: pnpm ...

NEXT.JS · CODEX · HARNESS TUTORIAL Codex로 무료 온라인 툴 사이트 만들기 하네스 적용부터 직접 따라 하기 오늘 적용한 AGENTS.md 하네스가 왜 필요한지 먼저 쉽게 설명하고, 이어서 프로젝트에 그대로 복사·붙여넣기 할 수 있는 문서와 Codex 요청문을 한 편에 정리했습니다. 이 글에서 다루는 내용 하네스를 적용한 이유 왜 문서를 나누나 폴더 구조 AGENTS.md docs 역할 Codex 사용 순서 먼저, 왜 Codex에 하네스를 적용했을까? 이번에 만들려는 것은 회원가입 없이 브라우저에서 바로 사용할 수 있는 무료 온라인 툴 사이트입니다. UUID 생성기, JSON Formatter, Base64, Timestamp Converter, QR Code Generator처럼 작은 도구를 하나씩 늘려 갈 계획입니다. 처음에는 “Codex에게 도구 하나씩 만들어 달라고 하면 되지 않을까?”라고 생각하기 쉽습니다. 그런데 도구가 늘어나면 기준도 함께 늘어납니다. 어떤 페이지는 오류 메시지가 영어이고, 어떤 페이지는 복사 버튼이 없을 수 있습니다. 어떤 기능은 입력값을 서버로 보내고, 어떤 기능은 브라우저 안에서 처리할 수도 있습니다. 이처럼 같은 사이트 안에서 규칙이 제각각이 되는 것을 막기 위해 하네스(harness) 를 적용했습니다. 하네스는 별도 프로그램이 아닙니다. Codex가 프로젝트를 작업할 때 먼저 읽고 지켜야 할 규칙, 안전 원칙, 확인 방법, 완료 기준을 적어 둔 프로젝트의 작업 안내서 입니다. 새 팀원에게 “우리는 이런 방식으로 일합니다”라고 알려 주는 짧은 온보딩 문서에 가깝습니다. 이 프로젝트에서는 그 중심 파일을 AGENTS.md 로 정했습니다. 코드와 파일명은 영어로, 사용자가 보는 문구와 오류 메시지는 한국어로 작성합니다. 가능한 기능은 브라우저에서 처리하고, 사용자 입력을 불필요하게 서버...

왜 토큰이 빨리 소모될까? 메시지를 보낼 때마다 이전 대화 전체(프롬프트, 응답, 도구 실행 결과 전부)가 처음부터 다시 전송되어 처리된다. 즉 토큰 사용량은 "내가 방금 입력한 양"이 아니라 세션이 시작된 이후 오간 모든 내용의 누적량 이다. 특히 Claude가 도구를 써서 파일을 읽거나 diff를 가져올 때마다 그 결과 전체가 대화 기록에 그대로 끼어들기 때문에, 무심코 큰 파일을 여러 개 읽게 하면 순식간에 컨텍스트가 불어난다.  💡 아래 명령어들은 모두 Claude Code를 실행 중인 터미널(또는 VS Code 통합 터미널) 안에서, 그냥 타이핑하고 Enter를 누르면 된다. 목차 01 세션 관리 02 CLAUDE.md 다이어트 03 작업에 맞는 모델 선택 04 MCP 서버 오버헤드 05 훅·스킬로 전처리 위임 06 서브에이전트 위임 07 확장 사고 조정 08 구체적인 프롬프트 09 Plan Mode + 조기 수정 10 코드 인텔리전스 플러그인 11 에이전트 팀 주의사항 12 서드파티 커뮤니티 도구 ＋ 사용량 확인 방법 ＋ 참고 자료 01 세션 관리 — 컨텍스트를 주기적으로 비우기 Claude Code는 세션이 길어질수록 이전에 시도했다 실패한 접근, 이미 해결된 에러, 더 이상 필요 없는 파일 내용까지 계속 컨텍스트에 들고 있는다. 아침에 시작한 세션을 점심 이후까지 그대로 이어가면, 실제로 지금 필요한 정보보다 "죽은 무게(dead weight)"가 더 많아질 수 있다. /clear 는 이 무게를 완전...