APC 명령어는 저장소(Repo)에 머뭅니다. APX는 단지 이를 읽을 뿐입니다.

APC를 약화시키는 가장 쉬운 방법은 .apc/commands/를 셸 스니펫(shell snippets)을 무작위로 던져두는 곳처럼 취급하는 것입니다.

그것은 핵심을 놓치는 것입니다.

APC는 휴대 가능한 컨텍스트 계층(portable context layer)입니다. APX는 일상적인 사용을 위한 런타임(runtime) 및 툴링(tooling) 계층입니다. 명령어(Commands)는 머신의 동작이 아니라 프로젝트의 동작을 설명하기 때문에 APC 측에 위치합니다.

APX는 해당 폴더를 유용하게 만들고, APC는 이를 휴대 가능하게 유지합니다.

.apc/commands/의 용도

APX 문서에서는 이미 명령어를 프로젝트 레이아웃의 일부로 취급하고 있습니다. apx init은 .apc/agents/, .apc/skills/, 그리고 .apc/commands/를 함께 생성합니다. 이는 명령어를 사후 고려 사항이 아닌, 일급 프로젝트 아티팩트(first-class project artifact)로 만들기 때문에 중요합니다.

APX는 또한 CLI를 통해 명령어를 직접 노출합니다:

• apx command list: .apc/commands/에 있는 워크플로(workflow) 명령어를 나열합니다.
• apx command show <name>: 명령어 내용을 출력합니다.

따라서 런타임(runtime)이 명령어를 소유하는 것이 아닙니다. 런타임은 단지 명령어를 발견하고 읽을 뿐입니다.

이것이 올바른 분리입니다.

마크다운(markdown)이 효과적인 이유

APC의 명령어 파일은 검토하기 쉽고, 차이(diff)를 확인하기 쉬우며, 다른 저장소로 복사하기 쉬워야 합니다.

마크다운이 이를 가능하게 합니다.

마크다운을 사용하면 의도를 문서화하면서도 파일을 작고 읽기 쉽게 유지할 수 있습니다. 명령어는 다음과 같이 보일 수 있습니다:

# Release checklist

1. Run tests.
...

이는 APX가 해당 파일을 다루기 전이라도 유용합니다. 팀원이 읽을 수 있고, 미래의 에이전트(agent)가 읽을 수 있으며, Git이 검토할 수 있습니다.

핵심은 마크다운이 마법 같다는 것이 아닙니다. 핵심은 마크다운이 명령어를 휴대 가능하게 유지한다는 점입니다.

무엇이 포함되어야 하는가

다음과 같은 프로젝트 관련 질문에 답하는 워크플로 수준의 지침은 .apc/commands/에 넣으십시오:

• 여기서 PR(Pull Request)을 어떻게 검토하나요?
• 릴리스(release)를 어떻게 준비하나요?
• 변경 사항을 어떻게 안전하게 요약하나요?
• 머지(merge)하기 전에 어떤 단계를 따르나요?

이것들은 프로젝트 규칙입니다. 따라서 프로젝트와 함께 있어야 합니다.

간단한 테스트 방법은 다음과 같습니다: 만약 깨끗하게 클론(clone)한 저장소나 다른 머신에서도 동일한 명령어를 원한다면, 그것은 APC에 속해야 합니다.

무엇이 포함되지 말아야 하는가

런타임 노이즈(runtime noise)를 .apc/commands/에 넣지 마십시오.

다음 항목들이 이에 포함됩니다:

• API 키 (API keys)
• 세션 기록 (session history)
• 특정 머신 전용 경로 (machine-specific paths)
• 임시 출력물 (temporary output)
• 단 하나의 노트북에서만 의미가 있는 모든 것

만약 파일이 상태(state), 비밀 정보(secrets), 또는 일회성 실행 세부 사항(one-off execution details)에 관한 것이라면, 대신 APX 런타임 저장소(runtime storage)에 보관하십시오.

APX에는 이미 그러한 로컬 상태(local state)를 위한 공간이 있습니다. APC는 클론 안전(clone-safe) 상태를 유지해야 합니다.

경계가 중요한 이유

이것이 분리의 진정한 가치입니다:

• APC는 프로젝트 계약(project contract)을 저장합니다.
• APX는 그 계약을 읽고 그에 따라 실행합니다.

명령어가 APC에 있으면, 저장소(repo)를 이동하더라도 워크플로우(workflow)를 유지할 수 있습니다.
명령어가 APX 런타임에 있으면, 저장소를 오염시키지 않으면서도 로컬 유연성(local flexibility)을 얻을 수 있습니다.

이는 도구가 변경될 때 예기치 못한 상황이 줄어든다는 것을 의미합니다. 또한 워크플로우가 코드와 함께 버전 관리(versioned)되므로, 에이전트(agents) 간의 드리프트(drift)도 줄어듭니다.

결론

.apc/commands/는 잡동사니 서랍(junk drawer)이 아닙니다.

이것은 프로젝트가 소유하고 APX에 의해 드러나는, 이식 가능한 워크플로우 계층(portable workflow layer)입니다.

만약 명령어가 이 저장소가 어떻게 작동하는지를 설명한다면, APC에 커밋(commit)하십시오.
만약 명령어가 단지 이 머신에서 무엇이 일어났는지만을 설명한다면, APX에 유지하십시오.

그 경계는 작지만, 나중에 발생할 수 있는 많은 혼란을 방지해 줍니다.