데코레이터 노드 설계의 모범 사례 (Best Practices for Decorator Node Design)

1. 개요

데코레이터 노드 설계의 모범 사례는 데코레이터를 올바르고 효율적이�� 유지보수 가능하게 구현하기 위한 핵심 지침을 정리한 것이다.

2. 핵심 설계 원칙

2.1 RUNNING 통과 보장

모든 데코레이터에서 자식의 RUNNING 상태를 변환하지 않고 그대로 전달한다. RUNNING을 변환하면 비동기 실행과 halt 메커니즘이 파괴된다.

2.2 halt()에서 내부 상태 완전 초기화

카운터, 타이머, 플래그 등 모든 내부 상태를 halt()에서 초기화하고, 기반 클래스의 halt()를 호출한다.

2.3 executeTick() 사용

자식을 tick할 때 child_node_->executeTick()을 사용한다. tick()을 직접 호출하면 상태 관리가 누락된다.

2.4 단일 책임 원칙

각 데코레이터는 하나의 동작 수정만을 담당한다. 여러 기능이 필요하면 중첩한다.

2.5 투명성 우선

가능한 한 데코레이터를 투명하게 설계하여, 추가/제거 시 행동의 핵심 논리에 영향을 미치지 않도록 한다.

3. 명명 규약

데코레이터의 이름은 수행하는 동작을 명확히 나타내어야 한다.

4. 포�� 설계

• 모든 포트에 단위를 명시한다 (예: msec, sec, m).
• 합리적인 기본값을 제공한다.
• 포트 이름을 일관되게 사용한다.

5. 중첩 깊이 제한

데코레이터 중첩은 3단계 이내로 제한한다. 그 이상이 필요하면 서브트리로 분리한다.

6. 테스트

• 모든 상태 입력에 대한 변환 테스트를 수행한다.
• halt 전파와 내부 상태 초기화를 검증한다.
• 타이밍 데코레이터는 시간 정밀도 테스트를 포함한다.

7. 안전 관련 데코레이터

안전에 중요한 행동에 ForceSuccess를 적용하지 않는다. Timeout을 모든 비동기 행동에 적용하여 무한 실행을 방지한다.

8. 참고 문헌

• Colledanchise, M., & Ogren, P. (2018). Behavior Trees in Robotics and AI: An Introduction. CRC Press.
• BehaviorTree.CPP 공식 문서. https://www.behaviortree.dev/