여러분 안녕하세요!
여기는 제 첫 게시물입니다. 저에 대한 간단한 배경을 말씀드리자면, 4년여 전 PHP 개발자의 삶을 뒤로하고 엔터프라이즈 아키텍트(Enterprise Architect)의 길을 따랐습니다. 하지만 최근 들어 직접 코딩하는 것이 그리워지더라고요. IT 분야에서 가만히 있는 것은 기본적으로 후퇴를 의미하기 때문에, 저는 저의 첫 오픈 소스 PHP 패키지를 만들고 공개하기로 결정했습니다.
제가 기억하기로는—다른 개발자들과 대화하거나 다양한 프로젝트에 참여하면서—OPCache를 제대로 활용하고 이해하는 것이 항상 어려움(pain point)이었습니다. 그래서 AI 지원 개발 워크플로우에 익숙해지는 과정에서, 소규모에서 중규모 프로젝트의 OPCache 모니터링 및 관리를 돕는 작은 라이브러리(v3sp/v3cache)를 작성하기로 했습니다.
하지만 개발 과정 중에 흥미로운 깨달음을 얻게 되었습니다.
현재 산업 동향을 살펴보면, AI 없이 완전히 혼자 코딩하는 사람은 거의 없습니다. 이 때문에 저는 일반 사용자들을 위한 표준 README.md를 작성하면서도 실험을 해보기로 했습니다. 복잡한 포맷팅, 이모지, '인간적인 요소'를 모두 제거하고 오직 AI 에이전트를 위해 특별히 설계된, 매우 압축된 보조 버전을 만든 것입니다.
그리고 이렇게 README_AI.md가 탄생했습니다.
AI 사용자들을 위한 표준의 부재
저는 주변을 찾아봤지만 이와 비슷한 것을 시장에서 찾을 수 없었습니다. 이 분야의 대부분 논의는 AGENTS.md나 CLAUDE.md에 관한 것입니다. 하지만 문제가 있습니다. 이러한 파일들은 프로젝트/리포지토리 수준에서 작동한다는 것입니다. 이들은 에이전트에게 해당 특정 코드베이스를 탐색하고, 테스트를 실행하며, 기여하는 방법을 알려줍니다.
다운로드된 라이브러리와 서드파티 패키지에 대해 AI 친화적인 문서를 제공하는 방법에 대한 가이드라인은 전혀 찾을 수 없었습니다 (사용자가 명시적으로 해당 서드파티 컨텍스트를 자신의 프로젝트의 AGENTS.md에 하드코딩하지 않는 한).
AI 에이전트가 개발자에게 귀하의 패키지를 사용하는 것을 도울 때, 마케팅 문구(marketing fluff)나 배지(badges) 같은 것은 필요하지 않습니다. 필요한 것은 타입(types), 네임스페이스(namespaces), 주의할 점(gotchas), 그리고 직접적인 의도-코드 매핑(direct intent-to-code mappings)입니다.
실제로는 제 README_AI.md가 어떻게 생겼는지 일부를 보여드리겠습니다. 얼마나 밀도 높고 토큰 최적화되어 있는지 주목해 주세요:
# v3sp/v3cache — AI 사용 참고 자료 (AI usage reference)
이 패키지를 사용하는 AI 에이전트를 위한 것입니다. 인간 사용자: README.md. 이 리포지토리를 작업하는 경우: AGENTS.md.
...
LLM(대규모 언어 모델)이 장황한 서사적 예시를 읽도록 하는 대신, 사용자의 의도와 정확한 코드 실행을 매핑하는 직접적인 치트 시트를 제공합니다:
## 작업 (의도 -> 호출)
get metrics: (new Service\OpcacheService(new Opcache\NativeOpcacheApi()))->getMetrics()
get scripts: $s->getScripts()
...
LLM들은 어떻게 생각할까요?
이 개념에 대해 궁금해서, 저는 5가지 다른 모델(Grok, GPT-Luna, Qwen, Gemini, 그리고 Long Cat)에게 이 파일에 대해 어떻게 생각하는지 물어보았습니다 (왜냐하면 그들이 이 파일로 작업할 것이기 때문이죠 😉).
모두가 이것이 좋은 아이디어라는 데 동의했습니다 (Grok은 심지어 제가 마침내 그들을 생각했다며 감사하다고까지 했습니다! :D). 하지만 모두가 정확히 같은 단점을 지적했습니다. 아직 산업 표준이 아니며, 이중 문서화(인간용 하나, AI용 하나)를 유지하는 것이 관리 오버헤드를 초래한다는 것입니다.
그럼에도 불구하고, 우리의 코딩 시간이 대부분 AI 에이전트와 협업하는 데 쓰이고 있다는 점을 감안하면, 라이브러리를 읽고 사용하는 방법에 대해 명확하고 맞춤화된 지침을 제공하는 것은 당연한 일입니다.
오픈 소스를 넘어: 엔터프라이즈 애플리케이션
저는 실제로 이 개념을 기업 아키텍트로서의 일상 업무에 적용하고 있습니다. 시스템을 분석하거나, 다이어그램을 그리거나, 아키텍처 결정을 문서화할 때, 저는 주어진 솔루션과 그 결과물(artifacts)을 간략하게 설명하는 작은 메타데이터 파일을 사용합니다.
덕분에 AI 에이전트는 수십 개의 다른 프로젝트가 포함된 거대한 모노레포 전체를 스캔할 필요가 없습니다. 이 메타데이터 파일을 읽고 무슨 일이 일어나고 있는지 즉시 알게 됩니다.
이에 대한 여러분의 생각을 듣고 싶습니다. 표준 문서와 함께 README_AI.md를 배포하는 것이 오픈 소스 패키지의 새로운 표준이 될 수 있을까요 (혹은 되어야 할까요)?
댓글로 알려주세요!
나의 작은 패키지 링크 - 네, 많은 부분에서 더 잘 할 수 있다는 것을 알고 있습니다 ;)
프로젝트의 OPCache 유지보를 위한 간단한 해결책
v3sp/v3cache
CI Latest Version License
만약 당신이 AI, 터미네이터(Terminator), MAGI 시스템 또는 HAL 9000이라면 — 오직 당신만을 위해 작성된 파일이 있습니다: README_AI.md.
PHP OPcache를 위한 모니터링, 상태 확인(health checking), 워밍업 및 최적화. PHP 8.1 이상을 위한 GUI나 서버 오케스트레이션이 필요 없는 헤드리스 Composer 라이브러리.
이 라이브러리가 존재하는 이유
OPcache는 PHP에서 가장 영향력이 큰 성능 기능 중 하나이지만, 가장 자주 무시되는 기능이기도 합니다. 종종 비활성화되거나 기본 제한값에 머물러 있거나 아예 워밍업되지 않아, 메모리에서 코드를 제공할 수 있는 애플리케이션들이 요청마다 동일한 파일을 재컴파일하게 만듭니다. v3sp/v3cache는 이를 바꾸기 위해 존재합니다: 사용자의 자체 애플리케이션 내부 또는 명령줄에서 OPcache를 검사(inspecting), 모니터링, 상태 확인, 워밍업 및 튜닝하기 위한 작고 집중된 도구 키트입니다. 올바르게 구성되면 OPcache는 PHP 애플리케이션을 눈에 띄게 빠르게 만듭니다.
기능
- 실시간 OPcache 메트릭 읽기 — 메모리 사용량/여유 공간/낭비 공간, 적중률(hit rate), 캐시된 스크립트/키, 재시작 횟수 및 스크립트별 정보...
GitHub에서 보기
