Imported from big-gates/agent-md-template (ko/rust-axum/AGENTS.md). Install upstream with npx skills add big-gates/agent-md-template --skill rust-axum. Copyright stays with the author.

AGENTS.md -- mcp-server 모듈

Name: rust-axum
Author: big-gates

1. 목적

mcp-server는 Rust/Axum 백엔드 모듈이다.

항목	값
언어	Rust 2024 edition
프레임워크	Axum 0.8.1 + Tokio 1.44.2
아키텍처	Hexagonal Architecture + Clean Architecture + DDD + TDD
API 포트	`:4070` (REST + WebSocket)
주요 의존성	`serde` 1.0, `serde_json` 1.0, `reqwest` 0.12, `chrono` 0.4, `uuid` 1.16, `thiserror` 2.0, `anyhow` 1.0, `tower-http` 0.6, `rust-embed` 8

2. 에이전트 문서 라우팅

에이전트가 작업할 파일 경로에 따라 아래 문서를 반드시 먼저 읽는다.

파일 경로 패턴	참조 문서
`domain/**/entities.rs`	ddd-guide.md
`domain/**/services.rs`	ddd-guide.md
`domain/*/_policy.rs`	ddd-guide.md
`domain/**/mod.rs`	ddd-guide.md, package-structure.md
`application/ports/**`	hexagonal-guide.md
`application/usecases/**`	usecase-guide.md, hexagonal-guide.md
`application/dto/**`	handler-guide.md, api-design-guide.md
`application/errors.rs`	error-handling-guide.md
`adapters/inbound/http/**`	handler-guide.md, hexagonal-guide.md
`adapters/inbound/websocket/**`	handler-guide.md, hexagonal-guide.md
`adapters/outbound/**`	hexagonal-guide.md
`infrastructure/**`	async-guide.md, package-structure.md
`**/mod.rs`	package-structure.md
`*/test`, `tests/*`	tdd-guide.md, unit-test-guide.md
`tests/**`	integration-test-guide.md

3. 프로젝트 전반 원칙

3-1. 아키텍처 의존성 방향

의존성은 항상 안쪽(domain)을 향한다. 바깥 레이어가 안쪽을 참조하며, 그 반대는 금지한다.

From \ To	`domain`	`application`	`adapters`	`infrastructure`
domain	--	금지	금지	금지
application	OK	--	금지	금지
adapters	OK	OK	--	금지
infrastructure	OK	OK	OK	--

// OK: application이 domain을 참조
use crate::domain::order::entities::Order;

// 금지: domain이 application을 참조
// use crate::application::dto::order::OrderDto;

3-2. Async-First 원칙

규칙	설명
런타임	Tokio (`#[tokio::main]`)
모든 I/O 함수	`async fn`으로 선언
블로킹 금지	`std::thread::sleep`, `std::fs` 동기 호출 금지 -- `tokio::time::sleep`, `tokio::fs` 사용
병렬 실행	`tokio::join!`, `tokio::select!`, `futures::join_all` 활용
백그라운드 작업	`tokio::spawn`으로 분리, 핸들 관리

3-3. TDD 원칙

규칙	설명
테스트 우선	기능 구현 전에 실패 테스트 작성
인라인 테스트 모듈	`#[cfg(test)] mod tests { ... }`
비동기 테스트	`#[tokio::test]` 사용
테스트 비율	Unit 70%, Integration 25%, E2E 5%
품질 게이트	`cargo fmt`, `cargo clippy -D warnings`, `cargo test` 모두 통과 필수
금지 패턴	프로덕션 코드에 `unwrap()`, `expect()`, `panic!()` 사용 금지

3-4. 코드 품질 체크리스트

cargo fmt -- 코드 포맷 통과
cargo clippy -D warnings -- 경고 없음
cargo test -- 모든 테스트 통과
프로덕션 코드에 unwrap() / expect() / panic!() 없음
의존성 방향 위반 없음 (domain이 외부 레이어를 참조하지 않음)
새 파일 작성 시 해당 mod.rs에 pub mod 선언 추가
DTO 변경 시 프론트엔드 TypeScript 타입과 동기화 확인

4. 에이전트 판단 규칙

4-1. 새 파일/구조체 생성 위치

대상	위치	예시
도메인 엔티티/값 객체	`{domain}/domain/model/entities.rs` 또는 새 파일	`Order`, `OrderItem`
도메인 서비스	`{domain}/domain/model/services.rs`	상태 없는 비즈니스 규칙
도메인 정책	`{domain}/domain/model/<policy_name>.rs`	`pricing_policy.rs`
Bounded Context	`{domain}/application/usecases/bounded_contexts/<context>.rs`	`order_lifecycle.rs`
UseCase (비즈니스 로직)	`{domain}/application/usecases/` 하위 파일	`checkout.rs`, `refund.rs`
DTO (요청/응답)	`{domain}/application/dto/<name>.rs`	Request/Response 구조체
Port (아웃바운드 인터페이스)	`{domain}/application/ports/outbound.rs`	trait 정의
HTTP 핸들러	`{domain}/adapters/inbound/http/mod.rs`	Axum handler 함수
WebSocket 핸들러	`{domain}/adapters/inbound/websocket/mod.rs`	WebSocket upgrade
영속성 어댑터	`{domain}/adapters/outbound/persistence/mod.rs`	DB/파일 저장
외부 서비스 어댑터	`{domain}/adapters/outbound/<service>/mod.rs`	API 클라이언트
설정	`{domain}/infrastructure/config/mod.rs`	`AppConfig`
부트스트랩	`{domain}/infrastructure/bootstrap/mod.rs`	런타임 초기화

4-2. 의존성 허용 테이블

작업 대상	`use domain::*`	`use application::*`	`use adapters::*`	`use infrastructure::*`
`domain/**`	OK	금지	금지	금지
`application/**`	OK	OK	금지	금지
`adapters/**`	OK	OK	OK (같은 adapter 내)	금지
`infrastructure/**`	OK	OK	OK	OK
`main.rs`	OK	OK	OK	OK

4-3. 커밋 전 필수 확인

cargo fmt
cargo clippy -D warnings
cargo test

5. 세부 지침 문서 위치

문서	경로	설명
아키텍처 개요	docs/architecture/README.md	전체 구조, 레이어 책임, 문서 색인
헥사고날 가이드	docs/architecture/hexagonal-guide.md	Port & Adapter 패턴, 의존성 규칙
패키지 구조	docs/architecture/package-structure.md	디렉토리별 역할 설명
DDD 가이드	docs/domain/ddd-guide.md	Aggregate, Entity, Value Object, Domain Event
UseCase 가이드	docs/domain/usecase-guide.md	Application Service 패턴
TDD 가이드	docs/testing/tdd-guide.md	TDD 사이클, 테스트 피라미드
단위 테스트 가이드	docs/testing/unit-test-guide.md	Mock, 인라인 테스트 패턴
통합 테스트 가이드	docs/testing/integration-test-guide.md	HTTP/WebSocket/Persistence 테스트
비동기 가이드	docs/rust/async-guide.md	Tokio 패턴, 채널, 구조적 동시성
네이밍 가이드	docs/rust/naming-guide.md	Rust 네이밍 컨벤션, 접미사 규칙
핸들러 가이드	docs/axum/handler-guide.md	Axum 핸들러, 라우터, 추출기
에러 핸들링 가이드	docs/axum/error-handling-guide.md	에러 타입, 상태 코드 매핑
Git 커밋 템플릿	docs/convention/git-commit-template.md	커밋 메시지 규칙
API 설계 가이드	docs/convention/api-design-guide.md	REST/WebSocket 설계 규칙

6. 문서 운영 규칙

규칙	설명
단일 진실 공급원	이 `AGENTS.md`가 mcp-server 모듈의 최상위 규칙이다
문서 갱신 의무	아키텍처 변경 시 관련 문서를 반드시 함께 갱신한다
신규 가이드 추가	`docs/` 하위에 추가하고, 이 파일 섹션 5에 등록한다
상위 문서 준수	프로젝트 루트 ../AGENTS.md 규칙도 함께 따른다
충돌 시 우선순위	이 파일 > 상위 AGENTS.md > 개별 가이드 문서
코드와 문서 불일치	코드가 진실이며, 문서를 코드에 맞춰 갱신한다

rust-axum

About

AGENTS.md -- mcp-server 모듈

1. 목적

2. 에이전트 문서 라우팅

3. 프로젝트 전반 원칙

3-1. 아키텍처 의존성 방향

3-2. Async-First 원칙

3-3. TDD 원칙

3-4. 코드 품질 체크리스트

4. 에이전트 판단 규칙

4-1. 새 파일/구조체 생성 위치

4-2. 의존성 허용 테이블

4-3. 커밋 전 필수 확인

5. 세부 지침 문서 위치

6. 문서 운영 규칙

Use it

Manifest

Reviews