Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 22. 22:40

AI가 읽을 수 있는 비즈니스 API를 위한 작은 PHP 프레임워크를 만들었습니다

요약

AI 에이전트가 읽고 활용하기 쉬운 비즈니스 API 구축을 위해 설계된 경량 PHP 프레임워크 NENE2를 소개합니다. OpenAPI 계약과 MCP 도구 지원을 통해 인간과 AI 모두에게 명확한 인터페이스를 제공하는 것을 목표로 합니다.

핵심 포인트

  • AI 에이전트 및 MCP 도구 활용을 위한 API 우선 설계
  • OpenAPI 3.1 및 RFC 9457 기반의 명확한 계약 준수
  • 복잡성을 배제한 작고 명시적인 아키텍처 지향
  • PSR 표준을 준수하는 안정적인 HTTP 런타임 환경 제공

저는 NENE2라고 불리는 작은 PHP 프레임워크를 만들어 왔습니다.

이것은 Laravel의 대체재가 아닙니다.
풀스택 (Full-stack) 프레임워크도 아닙니다.
모든 것을 마법(magic) 뒤로 숨기려고 시도하지도 않습니다.

NENE2는 **AI가 읽을 수 있는 비즈니스 API (AI-readable business APIs)**를 구축하기 위한 작고 API 우선적인 (API-first) PHP 기반입니다. 즉, 명시적인 HTTP 경계, OpenAPI 계약, Problem Details 에러, 그리고 AI 에이전트를 위한 선택적인 MCP 도구 카탈로그를 갖춘 작은 서비스들을 위한 것입니다.

저장소: hideyukiMORI/NENE2

왜 또 다른 PHP 프레임워크를 만드는가?

대부분의 비즈니스 소프트웨어는 아름다운 그린필드 (greenfield) 플랫폼으로 시작하지 않습니다.

다음과 같은 요청에서 시작됩니다:

  • "이 워크플로우를 API로 노출할 수 있을까요?"
  • "내부 도구가 이것을 안전하게 호출할 수 있을까요?"
  • "AI 에이전트가 데이터베이스를 직접 건드리지 않고 상태를 조회할 수 있을까요?"
  • "팀이 실제로 이해할 수 있을 만큼 충분히 작게 유지할 수 있을까요?"

대형 프레임워크는 그 생태계가 필요할 때 매우 훌륭합니다.

하지만 작은 비즈니스 API를 위해서는, 저는 종종 더 조용한 무언가를 원합니다:

  • 명시적인 라우트 (explicit routes)
  • 작은 핸들러 (small handlers)
  • HTTP를 알지 못하는 유스케이스 (use cases)
  • 리포지토리 인터페이스 (repository interfaces)
  • 공개 계약으로서의 OpenAPI
  • 예측 가능한 에러 응답
  • 동작을 증명하는 테스트
  • AI / MCP 도구를 위한 깨끗한 경계

그것이 바로 NENE2가 존재하는 설계 영역입니다.

핵심 아이디어: API 우선, AI 가독성

NENE2는 API가 주요 접점(surface)이라고 가정합니다.

서버 사이드 렌더링 (Server-rendered) HTML이 존재할 수 있고, React 프론트엔드 스타터가 존재할 수 있지만, 백엔드가 프론트엔드 빌드 접착제 (build glue)가 되어서는 안 됩니다. 안정적인 계약은 바로 HTTP API입니다.

이 프레임워크는 다음과 같은 요소들을 중심으로 구성됩니다:

  • PSR-7 / PSR-15 / PSR-17 HTTP 런타임 지침
  • 명시적인 라우팅 및 미들웨어 (middleware)
  • OpenAPI 3.1 계약 문서화
  • 에러를 위한 RFC 9457 Problem Details
  • 타입이 지정된 설정 객체 (typed configuration objects)
  • PSR-11 의존성 주입 (dependency injection)
  • PDO 데이터베이스 어댑터 및 트랜잭션 경계
  • 선택적인 React + TypeScript 프론트엔드 스타터
  • 동일한 API 경계 뒤에 있는 로컬 MCP 서버 지원

목표는 코드를 영리하게 만드는 것이 아닙니다.

목표는 인간 개발자, 리뷰어, 또는 AI 코딩 에이전트(AI coding agent)가 코드를 쉽게 검사할 수 있도록 만드는 것입니다.

의도적으로 지루한 아키텍처 (A boring architecture on purpose)

참조 도메인 예제는 다음과 같은 단순한 흐름을 따릅니다:

HTTP Handler
  -> Use Case
  -> Repository Interface
...

예를 들어, Note CRUD 참조 구현에는 다음이 포함됩니다:

  • route + handler 클래스
  • use case 클래스
  • readonly 입력/출력 DTO
  • repository interface
  • PDO repository
  • exception-to-Problem-Details 매핑
  • OpenAPI paths 및 schemas
  • unit, HTTP, 그리고 PDO 통합 테스트

이것은 의도적으로 지루하게 설계되었습니다.

저는 애플리케이션의 동작이 프레임워크의 관례(convention)에 의해 암시되는 대신, 파일 트리에서 명확히 보이기를 원합니다.

OpenAPI는 핸드오프 문서 (The handoff document)

NENE2에서 OpenAPI는 사후 고려 사항이 아닙니다.

이 리포지토리는 OpenAPI 3.1 문서, Swagger UI, 그리고 예제 엔드포인트(endpoints)를 위한 런타임 계약 테스트(runtime contract tests)를 함께 제공합니다.

로컬에서 앱을 시작한 후:

docker compose up -d app

유용한 URL은 다음과 같습니다:


...

이것이 중요한 이유는 OpenAPI 파일이 다른 도구들로 연결되는 가교 역할을 하기 때문입니다:

  • 생성된 클라이언트 (generated clients)
  • 계약 테스트 (contract tests)
  • 문서화 (documentation)
  • MCP 도구 카탈로그 (MCP tool catalogs)
  • AI 지원 개발 워크플로우 (AI-assisted development workflows)

API 계약(contract)은 공유된 언어입니다.

MCP가 "AI가 데이터베이스를 건드리게 한다"는 의미여서는 안 됩니다

NENE2의 아이디어 중 하나는 AI 에이전트(AI agents)가 문서화된 API 경계(boundaries)를 통해 작동해야 한다는 것입니다.

저는 에이전트가 프로덕션 테이블을 직접 쿼리하거나 변경(mutate)하는 것을 원하지 않습니다.

대신 다음과 같이 작동합니다:

AI Agent
  -> MCP Tool
  -> 문서화된 HTTP API
...

NENE2는 로컬 MCP 서버 지원과 도구를 OpenAPI 기반 작업으로 매핑하기 위한 가이드를 포함하고 있습니다.

읽기(Read) 도구는 상태를 검사할 수 있습니다.
쓰기(Write) 도구는 명시적인 인증(authentication)이 필요합니다.
애플리케이션은 여전히 검증(validation), 권한 부여(authorization), 로깅(logging), 그리고 에러 핸들링(error handling)의 주체입니다.

그 경계(boundary)를 유지하는 것이 중요한 부분입니다.

실제 앱을 통한 필드 테스트 완료

NENE2는 단순한 프레임워크 리포지토리가 아닙니다.

저는 다음과 같은 셀프 호스팅(self-hosted) 비즈니스 오픈 소스 소프트웨어(OSS) 프로젝트 제품군의 기반으로 이를 사용해 왔습니다:

  • NeNe Invoice — 일본 적격 청구서(qualified invoices)를 위한 견적 및 송장 관리
  • NeNe Vault — 전자 기록 보존을 위한 수신 문서 아카이브
  • NeNe Records — 타이핑 기반의 헤드리스 CMS (headless CMS) / 유연한 엔티티 (entity) 플랫폼
  • NeNe Deal — 경량 B2B 딜 파이프라인 (deal pipeline)
  • NeNe Contact — 임베드 가능한 연락처 양식
  • nene-mcp — OpenAPI 기반 HTTP API를 위한 stdio MCP 브리지 (bridge)
  • nene2-python — 동일한 철학을 구현한 Python 레퍼런스 구현체 (reference implementation)
  • nene2-js / nene2-node — TypeScript 생태계 구성 요소

이 제품 중 일부는 일본 시장에 특화되어 있습니다.
그것은 문제되지 않습니다.

핵심은 이 프레임워크가 실제 비즈니스 형태에 대해 검증되었다는 점입니다:

  • 인증 (authentication)
  • 멀티 테넌시 (multi-tenancy)
  • OpenAPI
  • 관리자 UI (admin UIs)
  • Docker 로컬 스택 (local stacks)
  • 데이터베이스 마이그레이션 (database migrations)
  • 내보내기 (exports)
  • 감사 로그 (audit logs)
  • MCP 카탈로그 (catalogs)
  • AI가 읽을 수 있는 문서화 (AI-readable documentation)

프레임워크 설계는 실제 애플리케이션을 통해 강제될 때 더욱 개선됩니다.

NENE2가 아닌 것

NENE2는 의도적으로 작게 설계되었습니다.

다음은 NENE2가 아닙니다:

  • Laravel 또는 Symfony의 대체재
  • 노코드 (no-code) 플랫폼
  • ORM 우선 (ORM-first) 프레임워크
  • CMS
  • 프론트엔드 프레임워크
  • AI 에이전트 런타임 (AI agent runtime)

NENE2는 명시적인 PHP API와 문서화된 핸드오프 지점 (handoff points)을 원하는 팀이나 1인 개발자를 위한 작은 기반입니다.

빠른 시작

리포지토리를 클론(Clone)하세요:

git clone https://github.com/hideyukiMORI/NENE2.git
cd NENE2
cp .env.example .env
...

또는 Composer 의존성으로 설치하세요:

composer require hideyukimori/nene2

NENE2는 PHP 8.4+를 대상으로 하며, 표준 개발 런타임으로 Docker를 사용합니다.

왜 "AI가 읽을 수 있는 것"이 중요한가

AI 보조 개발은 단순히 코드를 생성하는 것에 관한 것이 아닙니다.

그것은 또한 에이전트(agent)가 안전하게 도움을 줄 수 있을 만큼 시스템이 충분히 읽기 쉬운지에 관한 것이기도 합니다:

  • 라우트(route)를 찾을 수 있는가?
  • 요청(request)과 응답(response)의 형태(shape)를 이해할 수 있는가?
  • 유스케이스(use case)를 파악할 수 있는가?
  • 집중된 테스트(focused tests)를 실행할 수 있는가?
  • 유효성 검사(validation)를 우회하는 것을 방지할 수 있는가?
  • 데이터베이스 쿼리(database query)를 추측하는 대신 문서화된 도구(documented tool)를 호출할 수 있는가?

NENE2는 이러한 질문들에 대한 답이 명확해지도록 노력합니다.

더 많은 마법(magic)을 추가함으로써가 아닙니다.

모호함(ambiguity)을 제거함으로써 말입니다.

링크

저는 여전히 프레임워크와 그 주변의 NeNe OSS 시리즈를 다듬고 있습니다.

API-first PHP, OpenAPI, MCP, 또는 AI가 읽을 수 있는 비즈니스 소프트웨어에 관심이 있으시다면, 피드백을 언제든 환영합니다.

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0