효과적인 소프트웨어 설계 문서 작성법
https://t.co/cGJEfK6Y4W
글은 이렇게 시작하는데 우리가 읽을만할 많은 얘기를 담고 있어요.
"저는 구글, 마이크로소프트, 제 회사들에서도 개발자로 일하며 수많은 설계 문서를 작성해 왔습니다. 회사마다 세부적인 양식은 저마다 달랐지만, 관통하는 핵심 원칙은 같았습니다. 설계 문서의 본질은 내가 해결하려는 까다로운 문제가 무엇인지 명확히 드러내고, 팀원들이 유용한 피드백을 줄 수 있도록 돕는 것입니다."
설계 문서를 언제, 어느 정도로 작성해야 하는지에 대한 명확한 기준과 원칙을 참고할 수 있음.
[처음 배우는 AI] Prompt Template
Zero-shot은 바로 시키는 것, Few-shot은 예시를 보여주는 것이었다. 그런데 같은 형식의 질문을 매번 처음부터 쓰고 있다면, 그건 비효율이다.
Prompt Template은 반복해서 쓰는 지시문을 틀로 만드는 것이다. 항상 같은 부분은 고정하고, 바뀌는 부분만 빈칸으로 둔다. 한 번 잘 만들면 매번 새로 쓸 필요 없이 변수만 바꿔 넣으면 된다.
핵심은 두 가지다. 첫째, 누가 써도 같은 기준이 유지된다. 사람마다 묻는 방식이 달라서 답이 흔들리는 문제가 사라진다. 둘째, 같은 작업을 빠르게 반복할 수 있다. 이메일 초안, 회의록 정리, 보고서 요약 같은 반복 업무에 강하다.
주의할 점은 하나다. 낡은 틀은 업데이트해야 한다. 모델이 바뀌고 요구사항이 바뀌면 템플릿도 따라가야 한다. 한 번 만들어놓고 영원히 쓰는 건 없다.
매번 새로 쓰고 있는가, 한 번 만들어서 여러 번 쓰고 있는가?
#AI #처음배우는AI #프롬프트템플릿
Cursor나 Claude 같은 AI 도구에 큰 프로젝트를 넣으면 너무 느려지거나 돈이 많이 나오는데, 이걸 해결해 주는 초고속 코드 분석 도구임.
프로그램 언어 구성을 뼈대만 추려내서 지식 그래프로 만든 뒤 AI에게 넘겨주기 때문에 비용을 획기적으로 줄여줌.
복잡한 설치 과정 없이 파일 하나만 다운받아서 실행하면 바로 AI 에이전트들과 연동되니까 대형 코드를 다루는 개발자라면 함 써보셈.
AI가 프로처럼 디자인하게 만드는 DESIGN.md 라이브러리
🖼️ Refero Styles
https://t.co/n1y3qjdrZe
"완성된 디자인 시스템을 활용하세요"
"단순한 사양보다는 실제 사례를 보여주세요"
이런 Claude Design으로 더 나은 결과물을 내는 팁과 연결해서 활용할 수 있는 사이트!
주요 제품 웹사이트에서 가져온 2,000개 이상의 AI 인식 가능 디자인 시스템을 살펴보세요.
Refero Styles 은 Stripe, Linear, Vercel, Notion, ElevenLabs 등 실제 프로덕트들의 디자인 시스템을 AI가 바로 읽을 수 있는 DESIGN.md 형식으로 2,000개 이상 정리해 놓은 사이트 예요.
이런걸 다 가지고 있음..!
- 색상 팔레트 & 토큰
- 타이포그래피 스케일
- 스페이싱/레이아웃 리듬
- 컴포넌트 패턴
- 전체적인 무드와 가이드
Claude Code, Codex, Cursor, Lovable 같은데에서 이런 DESIGN.md를 붙여넣고 작업하면, 퀄리티 높은 제품 같은 느낌의 결과물을 기대해볼 수 있죠.
구글이 지난 8년 동안 AI 슈퍼컴퓨터를 어떻게 괴물로 키워왔는지 정리한 역대급 논문이 나왔습니다.
개발자나 실무자가 아니어도 한눈에 이해할 수 있게 핵심만 아주 쉽게 정리해 드립니다.
1/ AI 기술은 자고 일어나면 바뀔 정도로 빠르지만, 구글 TPU 반도체의 기본 뼈대는 8년째 큰 틀이 그대로입니다.
AI의 본질이 결국 '거대한 행렬 곱셈의 반복'이라는 걸 간파했기 때문이죠.
칩 내부에 곱셈만 미친 듯이 처리하는 바둑판 모양의 공장(MXU)을 딱 버티고 지어놓으니, 어떤 최신 AI 모델이 나와도 칩 대공사 없이 다 커버해 버립니다.
2/ 최신 7세대 시스템 '아이언우드(Ironwood)'의 규모는 상상을 초월합니다.
초기 모델보다 성능이 무려 3,600배나 뛰었습니다.
특히 AI가 데이터를 올려두고 일하는 '책상' 역할인 초고속 메모리(HBM)를 1.77PB(페타바이트)나 때려 박았습니다
. 축구장 만한 책상에 모든 백과사전을 다 펼쳐놓고 일하는 수준이라, 데이터 가지러 가느라 멍 때리는 시간이 아예 없습니다.
3/ 구글의 진짜 치트키는 '빛과 거울(OCS)' 기술입니다.
9,216개의 칩을 무거운 구리선 케이블로 연결하면 열이 나고 불타버립니다.
그래서 구글은 구리선 대신 레이저를 쏘고, 머리카락 만한 미세 거울로 빛을 반사해 칩들을 연결했습니다.
만약 일하다가 특정 칩이 고장 나면? 거울 각도를 슬쩍 틀어서 고장 난 칩만 실시간으로 우회해 버립니다.
고속도로에 사고 나자마자 순식간에 새 우회로를 뚫는 격이죠.
4/ 컴퓨터 9천여 대가 밤낮없이 돌면 우주 방사선이나 미세 전력 흔들림 때문에 데이터가 튀는 오류가 매일 발생합니다.
옛날엔 오류 나면 한 시간 전 저장 시점으로 돌아가서 처음부터 다시 계산해야 했습니다.
하지만 구글은 '하드웨어 리플레이' 기술을 씁니다.
오류가 감지되면 시스템을 끄지 않고, 오류 난 부품만 0.000001초 전으로 '되감기(Ctrl+Z)'해서 슥 다시 계산하고 아무 일 없었다는 듯 넘어갑니다.
5/ 결국 이 논문이 말하고자 하는 핵심은 이겁니다.
반도체 칩 자체의 성능도 중요하지만, 9,216개 칩에 일을 공평하게 쪼개주는 '천재 지휘자' 소프트웨어(XLA 컴파일러)와 전력 효율을 2배 높여 전기세를 아끼는 기술까지 전체 생태계를 완벽하게 통제해야 진짜 AI 슈퍼컴퓨터가 완성된다는 것.
구글이 왜 빅테크 중에서도 '인프라 깡패'로 불리는지 증명한 백서네요.
[처음 배우는 AI] Instruction Following
AI에게 "요약해줘"라고 말하면 요약을 한다. 그런데 3줄로 해달라고 했는데 10줄이 나오고, 표로 달라고 했는데 글로 나오고, 추측하지 말라고 했는데 추측이 섞여 있다. AI가 지시를 못 따르는 게 아니다. 지시가 어떤 구조로 되어 있는지 이해하면 왜 그런지 보인다.
Instruction Following은 AI가 목표, 조건, 형식, 금지사항을 구분해 따르는 능력이다. 이 네 가지를 분리하면 결과가 달라진다.
흐름은 단순하다. 목표를 읽고, 조건을 확인하고, 형식을 맞추고, 금지를 지키고, 결과를 점검한다. 빠뜨리기 쉬운 건 네 번째다. 무엇을 하라는 지시는 누구나 준다. 무엇을 하지 말라는 지시가 빠지면 AI는 허용된 범위를 최대한 넓게 쓴다. 결과가 부풀어오르고, 불필요한 것이 붙고, 원하는 것과 멀어진다.
그래서 좋은 지시에는 "해라"와 "하지 마라"가 같이 들어간다. 금지가 지시보다 강하다. "3줄로 써줘"보다 "4줄 이상 금지"가 더 정확하게 작동한다.
AI에게 무엇을 시키고 있는가, 무엇을 하지 말라고 말하고 있는가?
#AI #처음배우는AI #InstructionFollowing
AI 네이티브 기업 만드는 순서는 우선 '맥락'을 쌓는 데서 출발한다.
도구는 헤르메스를 쓰던, 오픈클로를 쓰던, 클로드를 쓰던 상관없다.
1. 우선 맥락, 즉 회사의 회의록이나 의사결정 문서, 오늘 할일/완수한 일 등을 사람이 계속 데이터로 밀어넣는 행동부터 해야 한다.
2. 회의록를 데이터로 쌓는 것부터 한다. 노션이든, 플라우드노트든, 일반 녹음이든 자동을오 회의록이 매일 md나 기타 내용으로 적재될 수 있도록 처리한다.
3. 사내의 업무기록일지와 회사 홈페이지 등을 활용해 전체 회사 도표와 업무 등 SOP와 SSOT 초안을 만드는 것이 중요하다. 그 초안을 만들고 매일 회의록이나 업무 일지 통해 자동 갱신하도록 크론잡을 돌린다.
4. 매일 회의록과 데이터가 적재되고, SOP가 갱신되려면 1일 1~2회 크론잡을 헤르메스가 돌리던가, 오픈클로가 돌리던가 해야 한다. 슬랙 내부의 대화록 통해서 수집하도록 한다.
5. 문제는 이 쌓이는 구조 자체를 만든다는 것 자체가 챌린지다. 회의록 폴더를 매일 새로 생성시키고 쌓게끔 AI에게 지시해야 하고, 그걸 사람이 원할 때 들여다볼 수 있도록 옵시디언 vault로 열어서 쉽게 파악하게끔 하는 후행 작업이 필요하다.
6. 또한, SOP와 SSOT를 매일 자동 갱신하면서 결국 이후 조직의 구성원들에게 체감될 수 있을만한 결과물, 아티팩트를 체감시켜주는 것도 필요하다. 리더만 이걸 체감했고 인프라를 깔았다 한들, 모든 구성원의 체감되는 공감대가 없으면 AI 네이티브 기업은 꿈과 같은 이야기다.
7. 따라서 스스로 헤르메스가 매일 하는 일들이 직원들에게 '놀라움'을 줄 수 있도록 매일 AI가 직원들에게 태스크를 제시하게 하고, 그걸 자동화할 수 있도록 가이드해주는 작업들이 필요하다. 그것은 결국 리더의 몫이다.
8. 'AI 요금제 구독시켜줘도 안써요'는 당연하다. 왜냐면 리더가 미리 보여주지 못했기 때문이다.
9. 위 내용을 열심히 제작하는 이유는, 잭 도시는 회사가 '하나의 지능'이 될 수 있다고 믿고 사람이 없이도 AI가 훨씬 더 많은 일들을 대체할 수 있는 구조로 나아갈 수 있다고 이야기 했기 때문이다. (실제로 그는 4천명을 감원했다.)
10. Y컴비네이터가 최근 제시한 여러 AI네이티브기업 만들기 영상들을 통해서도 계속 배우고 있는데, 정말 유용하다. 다만 그들은 how를 알려주기보다는 what을 제시하는 데 가까우며, 이를 실제로 실천하는 한국 기업도 잘 없다는 사실을 발견했다.
이러한 고민의 결과를 영상으로 찍었다(1편) : https://t.co/6MYKEiodFs
실험 수기는 계속된다.
앤쓰로픽에서 클로드 코드 세션 40만개를 분석한 보고서를 발간함.
Pdf 파일 보기에 시간부족하시면
아래는 직역한 내용 참고하세요.
2025년 10월부터 2026년 4월까지 약 400,000개 세션(약 235,000명 사용자)을 프라이버시 보호 방식으로 분석했습니다.
사용자는 계획(What to do) 결정을 약 70% 담당하고, Claude는 실행(How to do it) 결정을 약 80% 담당합니다.
사용자 전문성이 높을수록 Claude가 한 지시당 더 많은 작업을 수행합니다.
소프트웨어 엔지니어가 아닌 다양한 직업군도 코딩 작업에서 엔지니어와 거의 동등한 성공률을 보였습니다.
도메인 전문성이 높을수록 세션 성공률이 높으나, 중급자와 전문가 간 격차는 상대적으로 작습니다.
7개월간 디버깅 비중이 절반 가까이 감소하고, end-to-end agentic 사용(배포, 데이터 분석, 비코드 문서 작성 등)이 증가했습니다.
처리되는 작업 가치가 프리랜서 구인 게시물 기준으로 평균 25% 상승했습니다.
연구 배경
Claude Code CLI, 웹, 데스크톱 앱을 통해 수행된 대화형 코딩 세션을 9가지 작업 모드(빌드, 수정, 테스트, 운영, 계획, 이해, 분석, 커뮤니케이션 등)로 분류하고, 사용자 전문성 수준과 직업군을 추정했습니다.
결론
agentic coding 도구가 복잡하고 가치 있는 작업을 처리함에 따라 전문 지식을 보유한 사용자가 더 큰 이점을 얻을 것으로 전망됩니다.
위 보고서 요약을 보고
제가 내린 결론
도메인 지식은 무시못합니다.
현장에서 많은 경험을 쌓으세요.
나중에 에이전트 아키텍처 설계할 때 참고하기 좋은 12단계 로드맵임.
파이썬 비동기 기초부터 프롬프트 제어, Pydantic 구조화 출력, 컨텍스트 압축, LangGraph 오케스트레이션, 그리고 최종 vLLM이랑 쿠베 배포까지 백엔드와 인프라 전 과정을 관통함.
단순 API 호출말고 토큰 비용과 지연 시간 해결할 때 꺼내봐야 할 체크리스트
비개발자도 AI 생태계를 제대로 이해할 수 있게 해주는 최고의 사이트를 찾았어요!
📙 The Dictionary > Non-Technical Technical
https://t.co/CFIqn2PJww
사이트 제목 그대로 기술/AI 용어 100개를 진짜 친절하고 이해 쉽게 설명해주는 사전 사이트예요.
제가 읽어보니 정말 좋더군요.
딱딱한 정의로 끝나는게 아니라, 이게 왜 중요한지 + 실제로 어떤 느낌인지 이런걸 잘 풀어냈어요.
그리고 개념을 잡는 데 진짜 효과적입니다! 특히 비유가 압도적으로 좋아요 👍🏻
한 번 읽으면 머릿속에 개념이 착착 박히죠!
그런데 이게 읽다보니 꼭 비개발자가 아니어도 큰 도움이 되더라구요.
오히려 AI를 어느 정도 쓰고 있는 사람일수록 더 유용해요.
왜냐면 Agent, RAG, Function Calling, Guardrail, Prompt Injection 같은 개념들이 어떻게 연결되는지 전체 그림을 그릴 수 있게 해주거든요.
AI 생태계를 이해하는 데 정말 좋은 가이드입니다.
영문으로 제공되지만 브라우저에서 맞는 언어로 번역하면 전혀 문제 없어요.
💬 "코드를 세 번이나 배우려다 포기했지만, AI 덕분에 아이디어를 구현할 수 있게 되었어요.
이제 다른 사람들도 용어를 제대로 이해하고 더 좋은 질문을 할 수 있게 도와주고 싶어요."
DEJA DE PROMPTEAR. EMPIEZA A LOOPEAR.
Encontré un sitio que recopila los loops más usados por la comunidad
→ https://t.co/jNdeuXX9SW
Los propios creadores de Claude Code lo dicen: el futuro no es promptear, es diseñar loops.
No sabes qué son ni cómo crearlos?
Este articulo lo explica detalladamente👇
📕 AI 프롬프팅 마스터 클래스: 초보자에서 파워유저까지!
한국어 정리 문서는 여기요!
https://t.co/oQ7xCIiTbt
세계적인 AI 석학 앤드류 응 교수님의 엄청난 프롬프팅 강좌예요.
AI 초보자를 넘어 현재의 AI 도구를 더 잘 능숙하게 다루는 유저로 성장할 수 있도록 도와주죠.
AI에게 올바른 맥락을 제공하는 법과 무조건적인 동조를 방지하는 법, 알맹이 없는 글쓰기를 피하는 체계적인 워크플로우를 다루고 있어요.
여기에 나아가 실시간 정보 탐색을 위한 Deep Research부터 코딩 없이 앱을 만드는 멀티모달 활용, 코드 실행을 통한 데이터 분석까지..!!
다양한 실습 랩과 프로젝트 가이드도 함께 포함되어 있어요. 큰 도움 되실거예요.
📘 Codex CLI: 최종 기술 레퍼런스
https://t.co/uYi4WHLSwJ
한국어 버전이라 더 좋음.. 주요한 시스템을 아주 깊고 체계적으로 정리해 놓았네요.
Codex 원래 좋았는데 요즘 더더 좋아지고 있죠.
config.toml 우선순위, 샌드박스 모드와 승인 정책, AGENTS.md 작성법, 프로토콜, 스킬 시스템까지~~
Workflow 레시피 한번 참고해보세요. 일반적인 개발 시나리오를 위한 end-to-end 패턴!
자료가 서말이어도 꿰어야 보배다- Markitdown
무려 마이크로소프트가 만든 .md변환 툴 입니다. (무료)
오픈소스, 무료 .md변환툴입니다.
다양한 파일(PDF, Word, PPT, Excel, 이미지, 오디오 등)을 LLM(대형 언어 모델)이 쉽게 받아먹을 수 있는 깔끔한 Markdown(.md)으로 변환.
Microsoft Research에서 LLM 벤치마크와 AutoGen 프로젝트를 진행하면서, 파일을 AI가 먹기 좋게 준비하는 과정이 너무 복잡하고 번거로웠기 때문에 만들었다고 합니다.
기존 도구들은 구조(표, 제목, 리스트)를 제대로 유지하지 못하거나, 여러 포맷 지원이 약했음. 마이크로소프트가 내부 필요를 해결하다가 세상에 공개 했고 폭발적인 인기를 얻었습니다. (깃허브 10만+스타)
장점
-가볍다.
-PDF, DOCX, PPTX, XLSX, HTML, CSV, JSON, 이미지(PNG/JPG), 오디오(MP3/WAV), ZIP 오만것 다돌아 간다.
-CLI는 물론 VS Code 확장 만으로도 사용가능!
-에르메스나 오픈클로와도 연동가능
사용법
터미널 - pip install 'markitdown[all]'
저는!
VS Code에서 확장 프로그램으로 쓰고있는데 좋습니다.
확장탭에서 markitdown검색후 설치합니다.
변환하고자 하는 파일을 우클릭하면 제일 하단에 "Convert to Markdown" 이라고 있어요. 클릭후 기다리면 같은폴더안에 변환된 파일이 생성!
https://t.co/iRBJHF99qf
앤스로픽이 Claude Fable 5 내부에 심어둔 프롬프트 룰셋이 깃허브에 통째로 뜸.
클로드가 똑똑하고 예의 바르게 행동하던 비결이 사실은 엄청나게 긴 잔소리 프롬프트 덕분이었음.
이번에 유출된 클로드 패블 5 시스템 프롬프트를 보면 그 실체가 다 나옴.
유저가 무례하게 굴어도 굴복하지 말라는 멘탈 관리부터 저작권 시비를 피하려고 소스 인용을 딱 15단어로 제한하는 룰까지 앤스로픽의 방어 비책이 다 들어있음.
LLM으로 서비스 만들 때 가드레일 어떻게 치는지 궁금하면 무조건 열어봐야 할 교과서임.
📋 Loop Engineering
> 프롬프트를 AI 코딩 에이전트로 던지는 시대는 달라지고 있어요
Addy Osmani의 이 아티클은 한번 읽어보셨으면 좋겠어요. 정리해보면 이래요.
Peter Steinberger는 이렇게 말했어요.
> "이제 코딩 에이전트에게 직접 프롬프트를 보내면 안 됩니다. 에이전트를 프롬프트하는 루프를 설계해야 합니다."
Boris Cherny도 같은 말을 했죠.
> "나는 더 이상 Claude에게 직접 프롬프트하지 않아요. 내 일은 루프를 작성하는 것.."
↓
루프를 만드는 다섯 가지 요소 + 메모리
1. Automations - 주기적으로 스스로 일감을 찾아오는 자동화
2. Worktrees - 여러 에이전트가 동시에 작업해도 파일이 충돌하지 않게 하는 격리
3. Skills - 프로젝트의 맥락과 규칙을 파일로 남겨 매번 설명하지 않게 하는 것
4. Plugins & Connectors - 이슈 트래커, Slack, CI 같은 외부 도구와 연결
5. Sub-agents - 작성하는 에이전트와 검토하는 에이전트를 분리
그리고 여섯 번째로 중요한 건 Memory..
단일 대화가 아니라 외부에 상태를 기록하는 공간이 필요하다는 거죠. markdown 파일이나 Linear 보드 같은..
↓
중요한 이유는 있어요
모델은 실행이 끝나면 모든 걸 잊어버려요. 그래서 메모리는 컨텍스트가 아니라 디스크에 있어야 합니다.
> "모델은 잊지만, 레포지토리는 잊지 않습니다!"
이 한 문장이 루프 엔지니어링의 본질을 가장 잘 설명하는 것 같아요.
Claude Code의 /loop, /goal, worktree isolation 같은 기능들이 이 구조와 거의 1:1로 맞아떨어집니다. Codex도 마찬가지고요.
특히 /goal은 지정한 조건이 충족될 때까지 반복 실행하는데, 완료 판단을 코드를 작성한 모델이 아니라 별도의 모델이 한다는 점이 흥미롭습니다. Sub-agents 철학이 종료 조건에도 적용된 거죠.
↓
루프가 여전히 해결해주지 못하는 것들
루프가 아무리 정교해져도 결국 남는 문제들이 있어요.
- Verification은 여전히 사람이 해야 해요. 루프가 혼자 돌아가면서 실수도 혼자 저지르기 때문이죠.
- Comprehension Debt > 루프가 코드를 빠르게 생산할수록, 내가 실제로 이해하는 양은 점점 줄어듭니다.
- Cognitive Surrender > 루프가 잘 돌아가기 시작하면, 결과를 무비판적으로 받아들이게 되는 위험.
마지막으로 이 얘기는 계속 자문해야 한다고 봐요.
> "똑같은 루프를 만들어도 결과가 정반대인 두 사람이 있습니다. 한 명은 깊이 이해하는 일을 더 빠르게 하기 위해 루프를 쓰고, 다른 한 명은 이해를 피하기 위해 루프를 씁니다. 루프는 그 차이를 모릅니다. 당신만 압니다."
> "루프를 만들되, 엔지니어로 남아 있으려는 사람이 루프를 만들어야 합니다. 그냥 '시작' 버튼을 누르는 사람이 되지 말고..."
루프 설계는 프롬프트 엔지니어링보다 어렵지, 쉽지 않습니다.
AI한테 코딩 시켜놓고 결과 나올 때까지 한참 기다렸다가 검토하고 고치는 과정이 꽤 번거로움.
이 귀찮은 대기 시간을 없애기 위해 작업 방식을 완전히 바꾸는 방법임.
Claude Code 3개를 동시에 켜서 글쓰기, 검토하기, 수정하기를 각자 따로 수행하게 만드는 세팅임.
사람은 마지막에 완성된 최종 보고서만 확인하면 되니까 개발 속도가 확 빨라짐.
[처음 배우는 AI] AI Agent 용어 정리
AI Agent를 처음 배울 때 막히는 건 용어다. 핵심 7개를 한 장에 정리했다.
Agent는 목표를 보고 다음 행동을 고르는 실행 단위다. 똑똑한 챗봇이 아니라 도구를 쓰는 작업자에 가깝다. 그 도구(Tool)가 검색·파일·코드 실행처럼 바깥세상과 연결되는 손이다. Memory는 이전 작업과 중요한 사실을 다시 쓰는 저장소, Context는 지금 판단에 들어온 자료와 지시문이다.
나머지 셋은 일을 안전하게 끝내는 장치다. Workflow는 목표→계획→실행→확인의 작업 흐름, Human Approval은 위험 행동 전에 사람이 확인하는 안전문, Evaluation은 결과가 맞는지 다시 보는 검증 단계다.
이 일곱 개가 한 줄로 이어진다. 목표를 정하고, 계획을 세우고, 도구를 쓰고, 결과를 확인하고, 고친다. Agent는 이 흐름을 스스로 도는 존재다. 그래서 "답을 잘하는 AI"가 아니라 "일을 끝까지 끌고 가는 AI"가 핵심이다.
#AI #에이전트