[2025.11.14 주간 개발 트렌드] Spring Framework 7 정리 (Java 25, null 안전성, API 버전)

![주간 개발 트렌드](https://librarian-blog-images.s3.ap-northeast-2.amazonaws.com/b28d786c-9ec3-46ec-8055-adcd53a303c5_thumbnail_2.png)

# Coding Agent에게도 팀의 개발 규칙이 필요하다

AI에게 코드를 수정해달라고 했는데 프로젝트에서 사용하지 않는 패턴으로 작성하는 경우가 있다. 실행은 되지만 팀의 구조와 맞지 않아서 다시 설명해야하는 상황이다.

이번주 11월 5일에 GitHub가 [Copilot coding agent의 조직 공통 지침 지원](https://github.blog/changelog/2025-11-05-copilot-coding-agent-supports-organization-custom-instructions/)을 공개했다. 저장소별 규칙과 함께 조직 전체에 기본 지침을 적용할 수 있게 됐다.

이번주에는 어느 모델이 코드를 잘 작성하는지와 함께 Agent에게 어떤 개발 환경을 설명할지도 중요해지는 흐름을 정리해보려고 한다.

# 1. 우선 반복해서 설명하는 내용을 찾아보자

새로운 팀원이 프로젝트를 처음 열었다고 생각해보자. 언어와 프레임워크만 알아서는 어디를 수정하고 어떤 명령으로 검증해야하는지 바로 알기 어렵다.

Agent도 비슷한 정보를 필요로 한다. 저장소 전체를 읽으면 알 수 있을것 같지만, 코드에 드러나지 않는 결정이나 예외도 있다.

```text
프로젝트를 이해하는데 필요한 정보
├── 어떤 모듈이 어떤 책임을 가지는가
├── 공통 코드는 어디에 두는가
├── 어떤 명령으로 실행하고 테스트하는가
└── 변경할때 지켜야하는 제약은 무엇인가
```

매번 프롬프트에 같은 내용을 넣고있다면 문서로 남길 후보라고 볼 수 있겠다. 특히 사람이 구두로만 알고있는 규칙부터 정리하면 팀에도 도움이 된다.

단순히 좋은 코드를 작성하라는 문장보다 실제 프로젝트에서 사용하는 명령과 경로가 훨씬 구체적인 정보를 준다.

# 2. 조직 지침과 저장소 지침은 역할이 다르다

이번 기능은 조직의 coding agent 사용에 공통 기본 지침을 제공한다. 모든 저장소가 공유하는 원칙을 한곳에서 관리할 수 있는 방향이다.

반면 실제 실행 명령과 모듈 구조는 저장소마다 다를 수 있다. 같은 조직에서도 Node.js 서버와 Java 서버의 테스트 방법은 다를것이다.

| 범위 | 담기 좋은 내용 |
| --- | --- |
| 조직 | 변경 설명 방식, 공통 리뷰 원칙, 기본 검증 기대 |
| 저장소 | 실행 명령, 디렉터리 구조, 기술 선택의 이유 |
| 특정 영역 | 해당 모듈의 책임과 추가 검증 방법 |

조직 문서에 모든 프로젝트의 세부 사항을 넣으면 관련없는 규칙까지 읽게된다. 공통으로 적용할 수 있는 내용과 해당 저장소에서만 유효한 내용을 나누면 좋겠다.

지침이 서로 다른 말을 하고있다면 문서부터 정리해야한다. 충돌을 Agent가 알아서 추측하게 두면 작업마다 다른 결과를 받을 수 있다.

이번 발표에서는 .github/copilot-instructions.md와 경로별 instructions 파일, AGENTS.md, CLAUDE.md, GEMINI.md 지원도 함께 안내했다. 이 목록은 Copilot coding agent의 지원 범위로 이해해야한다. 모든 AI 도구가 같은 파일을 같은 규칙으로 읽는다는 뜻은 아니다.

# 3. 어떤 지침이 도움이 될까

예를 들어 다음처럼 검증 가능한 형태로 적어볼 수 있다. 명령어는 가상의 Node.js 프로젝트를 기준으로 한 예시다.

```markdown
- 패키지 매니저는 pnpm을 사용한다.
- API 라우트는 요청 검증과 응답 처리를 담당한다.
- 비즈니스 규칙은 service 계층에 둔다.
- 동작을 바꾸면 관련 테스트를 실행한다.
- pnpm test로 테스트하고 pnpm lint로 검사한다.
- 실행하지 못한 검증은 결과 설명에 남긴다.
```

이런 지침은 결과를 확인할 기준을 제공한다. 반대로 유지보수하기 좋은 구조로 작성하라는 문장만 있으면 사람마다 해석이 달라질 수 있다.

금지사항만 길게 나열하는것도 생각해볼 문제다. 무엇을 하면 안되는지와 함께 어떤 경로로 해결하면 되는지 알려줘야 작업을 진행하기 쉽다.

규칙의 이유도 짧게 남겨두면 좋겠다. 공통 모듈을 수정하지 말라는 문장보다 여러 서비스가 공유하고있으니 영향 범위를 확인하라는 설명이 판단에 도움이 된다.

문서에 적은 명령이 지금도 실행되는지도 확인하자. 잘못된 테스트 명령을 정확히 따라가는것은 좋은 결과로 이어지지 않는다.

# 4. 지침은 코드와 함께 관리해야한다

프로젝트 구조가 바뀌었는데 Agent용 문서만 예전 상태라면 서로 다른 설계를 설명하게된다. 지침도 변경의 영향을 받는 개발 문서로 보는게 좋겠다.

```text
구조나 명령 변경
    ↓
관련 지침 수정
    ↓
작은 작업으로 동작 확인
    ↓
리뷰 후 함께 반영
```

예를 들어 테스트 명령을 나눴다면 어떤 변경에 어떤 검증을 실행할지도 같이 고쳐야한다. 문서 파일이 존재한다는 사실보다 현재 개발 방식과 맞는지가 중요하다.

모든 내용을 한 파일에 넣기보다는 필요한 위치의 설명을 연결하는 방식도 생각할 수 있다. 다만 참조가 너무 깊어지면 핵심 규칙을 찾기 어려우니 자주 필요한 내용은 바로 읽을 수 있게 두면 좋겠다.

사람이 리뷰할때도 이 규칙이 실제로 지켜질 수 있는지 확인해야한다. 매번 예외가 생기는 지침이라면 코드보다 문서의 표현이 잘못됐을 수도 있다.

# 5. 규칙을 적었다고 검증이 끝나는것은 아니다

Agent 지침은 개발 방향을 설명하는 수단이다. 권한 제어나 CI의 필수 검사를 대신하는 강제 장치로 생각하면 안된다.

테스트를 실행하라고 적었다면 어떤 테스트를 실행했고 결과가 무엇인지 확인해야한다. 변경 범위를 작게 하라고 적었다면 실제 diff가 요청과 연결되는지도 살펴보자.

```text
확인할 결과
요청 이해 → 변경 범위 → 코드 동작 → 검증 결과 → 설명
```

지침을 평가할때는 같은 유형의 작은 작업을 몇개 골라 비교해볼 수 있다. 불필요한 파일 수정이 줄었는지, 맞는 테스트를 선택했는지, 실패한 검증을 숨기지 않는지 보는것이다.

한번 원하는 결과를 받았다는 이유로 문서가 완성됐다고 볼 필요는 없다. 반복되는 오해를 발견했을때 실제 예시를 기준으로 문장을 고쳐나가면 좋겠다.

# 마무리

이번 Copilot 소식은 AI 코딩이 모델 선택에서 끝나지 않고 팀의 개발 규칙과 문서 관리까지 연결되고있다는 의미로 보인다.

개인적으로는 Agent에게 반복해서 설명하는 내용이 프로젝트 문서의 빈칸을 보여준다는 점이 흥미롭다. 사람이 처음 참여해도 필요한 정보일 가능성이 높기 때문이다.

우선 실행 방법과 테스트, 모듈의 책임부터 짧게 정리해보면 좋겠다. 지침을 길게 작성하는것보다 현재 프로젝트에서 맞는 설명인지 계속 확인해야겠다..


[2025.11.07 주간 개발 트렌드] Copilot 조직 지침 정리 (개발 규칙, Agent 문서, 검증)

독자의 메모