AI 도구 사용에는 처음에는 편리해 보이는 지름길이 있습니다.

우리는 도구, MCP 서버, GitHub 연동, 로컬 명령 실행기(command runner) 또는 작업 트래커(task tracker)를 연결합니다. 그 후, 인터페이스는 이제 에이전트(agent)가 저장소(repositories), 작업(tasks), 풀 리퀘스트(pull requests), 파일(files) 및 명령(commands)과 함께 작업할 수 있다고 제안하기 시작합니다.

하지만 진지한 팀에게 그것만으로는 충분하지 않습니다.

기술적 능력(Technical ability)은 권한(permission)과 동일하지 않습니다. 그리고 허용된 작업이라 할지라도 여전히 인간의 결정이 필요할 수 있습니다.

이것이 바로 NexFlow가 이 요소들을 분리하는 이유입니다.

맥락을 설명하자면, NexFlow는 AI 개발 팀을 실행하기 전에 에이전트(agents), 역량(capabilities), 권한(permissions), 컨텍스트(context), 메모리(memory), 핸드오프(handoffs) 및 인간 승인 게이트(human approval gates)를 기술하기 위한 오픈 사양 우선(specification-first) 프로젝트입니다.

역량(Capability)은 한 가지 질문에 답합니다: 행위자(actor)나 연동(integration)이 기술적으로 무엇을 할 수 있는가?

권한(Permission)은 또 다른 질문에 답합니다: 특정 주체(subject)가 해당 역량을 사용하는 것이 허용되는가?

승인 게이트(Approval gate)는 세 번째 계층을 추가합니다: 해당 작업이 실행되기 전에 명시적인 승인이 필요한가?

이것은 작은 차이처럼 보일 수 있습니다. 하지만 실제로 이는 AI 보조 워크플로(workflow)가 검토될 수 있는지, 아니면 단순히 "에이전트가 이해할 것"이라는 희망에 의존해야 하는지를 결정합니다.

기술(Skill), 역량(Capability), 권한(Permission)

용어부터 시작하는 것이 좋습니다. 왜냐하면 혼란은 보통 여기서 시작되기 때문입니다.

기술(Skill)은 역할 적합성을 설명합니다. 예를 들어: schema_review, backend_review 또는 documentation_writing 등이 있습니다. 이는 행위자가 특정 유형의 작업에 적합함을 나타냅니다.

역량(Capability)은 작업 표면(action surface)을 설명합니다. 예를 들어: read_repository, write_repository, create_pull_request, execute_command, read_context, modify_documentation 또는 deploy_application 등이 있습니다.

권한(Permission)은 정책 결정(policy decision)을 설명합니다: 허용(allowed), 거부(denied), 또는 승인 후에만 허용(allowed only after approval).

승인 게이트(Approval gate)는 게이트가 설정된 작업(gated action)을 누가 또는 무엇이 승인해야 하는지를 설명합니다.

한 문장으로 요약하자면: 에이전트(agent)가 코드 리뷰를 수행할 기술(skill)을 가지고 있고, 통합(integration)이 create_pull_request라는 역량(capability)을 노출할 수 있더라도, 해당 에이전트가 실제로 풀 리퀘스트(pull request)를 생성할 수 있는지 여부는 권한(permission)이 결정해야 하며, 승인 게이트(approval gate)는 해당 작업이 실행되기 전 인간의 검토를 요구할 수 있습니다.

이것은 NexFlow에서 매우 중요한데, 에이전트, 인간, 자동화 시스템, 그리고 통합(integrations)이 모두 동일한 팀 설명(team description)의 일부이기 때문입니다. 연결된 도구라고 해서 모든 행위자(actor)에게 자동으로 권한을 부여해서는 안 됩니다.

역량(Capability)은 리스크 표면(risk surface)을 가시화합니다

역량(capability) 그 자체로는 아무것도 허용하지 않습니다.

하지만 리스크를 가시화합니다.

간소화된 역량(capability) 예시:

specVersion: "0.1"
kind: CapabilitySet
capabilities:
...

이 기록은 에이전트가 풀 리퀘스트(pull request)를 열 수 있다고 말하는 것이 아닙니다.

이것은 해당 프로젝트에 특정 리스크 프로필(risk profile)을 가진 작업이 포함되어 있음을 나타냅니다. 검토자(reviewer)는 런타임(runtime)이 작업을 실행하려고 시도하기 전에 이 작업 표면(action surface)을 확인할 수 있습니다.

고위험 작업의 경우, 이는 특히 중요합니다:

specVersion: "0.1"
kind: CapabilitySet
capabilities:
...

execute_command는 개발자 워크플로(workflow)에서 익숙해 보일 것입니다. 하지만 이는 너무 광범위해지기 쉬운 역량(capability) 중 하나입니다. 테스트를 실행하는 것과 의존성(dependency)을 설치하거나, 환경을 변경하거나, 파괴적인 명령(destructive command)을 실행하는 것은 전혀 다른 문제입니다.

역량(capability) 어휘(vocabulary)는 이러한 리스크가 프롬프트(prompt)나 UI 가정 속에 숨겨지지 않도록 유지합니다.

권한(Permission)은 결정을 내립니다

권한(permission)은 주체(subject)를 역량(capability)에 연결합니다.

NexFlow 초안 모델에는 세 가지 실질적인 효과가 있습니다:

allow
deny
approval_required

예를 들어, 문서 에이전트(docs agent)는 별도의 승인 없이 저장소(repository)를 읽을 수 있습니다:

specVersion: "0.1"
kind: PermissionSet
permissions:
...

하지만 동일한 문서 에이전트(docs agent)에 대해 명시적으로 제한을 둘 수도 있습니다:

specVersion: "0.1"
kind: PermissionSet
permissions:
...

이러한 규칙은 런타임(runtime)이 존재하기 전이라도 유용합니다.

이러한 규칙은 런타임(runtime)이 존재하기 전이라도 유용합니다.

정책을 검토 가능하게 만듭니다. 매니페스트를 읽는 사람은 에이전트의 역할뿐만 아니라 그 행동의 경계까지 볼 수 있습니다.

검토 후에만 허용되는 행동의 경우, 효과(effect)는 approval_required입니다:

specVersion: "0.1"
kind: PermissionSet
permissions:
...

이것은 UI 버튼이 아닙니다.

정책 경계입니다.

액터(actor)가 기술적으로 변경을 준비할 수는 있습니다. 하지만 기록에는 쓰기 작업이나 풀 리퀘스트 생성 전에 선언된 게이트가 필요하다고 명시되어 있습니다.

통합 기능(Integration capability)이 액터 권한이 아닌 이유

가장 흔한 실수는 통합 기능을 액터에게 옮기는 것입니다.

예를 들어, GitHub 통합이나 MCP 서버는 특정 기능이 필요하다고 선언할 수 있습니다:

requiredCapabilities:
  - create_pull_request

이는 단지 해당 통합이 풀 리퀘스트와 관련된 행동 표면(action surface)을 가지고 있다는 의미일 뿐입니다.

이것은 이 통합을 볼 수 있는 모든 에이전트가 풀 리퀘스트를 생성할 수 있다는 것을 의미하지 않습니다.

액터는 여전히 권한을 통해 승인되어야 합니다. 권한이 없다면, 미래의 런타임은 해당 행동을 거부해야 합니다. 만약 권한에 approval_required 효과가 있다면, 해당 행동은 게이트를 기다려야 합니다. 명시적인 거부(explicit deny)가 있다면, 게이트는 거부된 행동을 허용되는 행동으로 바꾸어서는 안 됩니다.

이 경계는 프로젝트를

예를 들어, 구현 에이전트(implementation agent)는 일반적으로 저장소(repository)를 다루는 것이 허용될 수 있습니다. 하지만 배포(deployment)는 별도로 거부될 수 있습니다. 만약 광범위한 허용(allow)이 우선한다면, 안전 규칙은 단순한 장식에 불과하게 됩니다. 만약 명시적 거부(explicit deny)가 우선한다면, 프로젝트 정책은 예측 가능한 상태를 유지합니다.

승인 게이트(approval gate) 또한 거부(deny)를 우회해서는 안 됩니다.

만약 특정 액터(actor)가 deploy_application을 거부당했다면, 승인 요청이 배포를 허용 가능한 것으로 만들어서는 안 됩니다. 권한 정책(permission policy) 자체가 변경되어야 합니다. 팀은 거부된 권한을 무효화하기 위해 단순히 '승인(approve)' 버튼에 의존해서는 안 됩니다.

승인 게이트란 무엇인가

승인 게이트는 의사결정 지점(decision point)을 설명합니다.

간소화된 예시:

approvalGates:
  - id: code_review
    description: Reviewer approval required before repository writes or pull request creation.
...

좋은 승인 게이트는 범위(scope)가 지정되어야 합니다.

하나의 풀 리퀘스트(pull request)에 대한 승인이 자동으로 배포를 허용해서는 안 됩니다. 하나의 명령(command)에 대한 승인이 명령을 실행할 수 있는 영구적인 권한이 되어서는 안 됩니다. 태스크 메모리(task memory) 쓰기에 대한 승인이 조직 메모리(organization memory) 업데이트를 허용해서는 안 됩니다.

미래의 런타임 시맨틱스(runtime semantics)에서 승인은 증거(evidence)를 수반해야 합니다: 누가 요청했는지, 무엇이 변경되는지, 어떤 파일이나 아티팩트(artifacts)가 영향을 받는지, 위험 요약(risk summary)은 무엇인지, 그리고 어떤 테스트나 검증 결과(validation outputs)가 존재하는지 등이 포함됩니다.

NexFlow는 현재 강제 집행(enforcement) 기능을 구현하고 있지 않습니다.

하지만 명세(specification) 어휘를 통해 인간의 권한(human authority)이 어디에 나타나야 하는지를 이미 기술할 수 있습니다.

런타임 이전에 이것이 유용한 이유

한 가지 타당한 질문이 있습니다: 런타임이 아직 매니페스트(manifests)를 실행하지 않는다면, 왜 이 모든 것을 작성해야 할까요?

그 이유는 검토(review)가 실행(execution) 전에 시작되기 때문입니다.

팀은 매니페스트를 읽고 다음 사항을 확인할 수 있습니다:

• 어떤 위험한 역량(capabilities)이 존재하는지;
• 어떤 액터(actors)가 저장소를 읽을 수 있는지;
• 누가 파일을 쓸 수 있는지;
• 어디에서 승인이 필요한지;
• 어떤 행동이 명시적으로 거부되었는지;
• 확장이 역량(capabilities)을 요구하지만 그 자체로는 권한(authority)을 부여하지 않는 곳은 어디인지.

이는 흩어진 프롬프트(prompts), 로컬 설정, 그리고 팀의 기억을 통해 권한을 파악하는 것보다 이미 훨씬 더 나은 방식입니다.

NexFlow는 여전히 명세 우선(specification-first) 프로젝트입니다. 저장소에는 초안 문서, 스키마(schemas), 예시, 그리고 RFC(Request for Comments)가 포함되어 있습니다. 런타임 강제(Runtime enforcement), 프로바이더 통합(provider integrations), 그리고 참조용 CLI(reference CLI)는 모두 향후 작업 과제입니다.

하지만 역량(capability), 권한(permission), 그리고 승인 게이트(approval gate)는 이미 리뷰를 위한 언어로서 유용합니다.

왜냐하면 AI 개발 팀에서는 에이전트(agent)가 무엇을 할 수 있는지만으로는 충분하지 않기 때문입니다.

중요한 것은 프로젝트가 에이전트에게 무엇을 할 수 있다고 명시하는가입니다.

그리고 어떤 지점에서 동작이 부작용(side effect)으로 이어지기 전에 인간이 반드시 개입하여 멈춰야 하는가입니다.