CLI Design Principles: Four-Layer Semantic Structure for AI-First Development

[deepracticexs]

Core Design Principles

This issue documents the foundational principles behind NodeSpec's CLI design. These principles guide all implementation decisions.

Principle 1: Four Independent Semantic Layers

nodespec [role] [domain] [action] [object] [...args]

Each layer provides distinct, independent semantic information:

• [role] - Responsibility context: Who is performing this task (职责上下文)
• [domain] - Workspace context: Which workspace to operate in, maps to directory structure (工作空间上下文)
• [action] - Intent context: What operation to perform (意图上下文)
• [object] - Instance context: The specific target of the operation (实例上下文)

Why this matters for AI:

• Each layer is independently meaningful
• AI can understand context with minimal inference
• Clear semantic boundaries reduce ambiguity

Principle 2: Role = Responsibility Boundary

Roles represent职责边界 (responsibility boundaries), not just user personas.

A role defines:

1. Who is performing the task
2. What domains are within their scope
3. What they care about vs what they don't

Value for AI:

• Role → implicit filtering of available domains
• Reduces context needed for command inference
• Natural grouping of related operations

Examples:

• `pm` role → cares about `feature`, not about `monorepo` structure
• `dev` role → cares about `app`, `service`, `package`, not about deployment
• `qa` role → cares about `test`, `step`, not about infrastructure
• `ops` role → cares about `docker`, `deploy`, not about features

Principle 3: Domain = Workspace Mapping

Domain暗含目录结构 (implies directory structure).

Each domain maps to a physical workspace:

• `monorepo` → project root (`./`)
• `app` → `apps/` directory
• `service` → `services/` directory
• `package` → `packages/` directory
• `feature` → `packages/[pkg]/features/` directory
• `test` → `packages/[pkg]/tests/` directory

Why this matters:

• Predictable file system operations
• AI can infer where files will be created
• Clear scope of operations

Principle 4: Action = Operation Verb

Actions are verbs, clear and direct.

Standard action patterns:

• Lifecycle: `init`, `create`, `start`, `stop`
• CRUD: `add`, `list`, `remove`, `update`
• Validation: `validate`, `verify`, `check`
• Execution: `run`, `watch`, `build`
• Generation: `generate`, `scaffold`

Why this matters:

• Consistent vocabulary across all domains
• AI recognizes patterns
• Predictable behavior

Principle 5: Object = Dynamic Target

Object is the specific instance being operated on.

The object is:

• Always dynamic (user-provided)
• The "what" after the "how"
• The concrete target of the abstract action

Why this matters:

• Clear separation of structure (role-domain-action) vs data (object)
• AI knows which part is template vs which is user input

Principle 6: AI-First Design Philosophy

Optimize for AI pattern recognition, not human memory.

From Issue #11:

"Optimize for AI's strengths (pattern recognition), not human weaknesses (memory)"

Design decisions:

• Longer but structured > shorter but ambiguous
• Explicit semantics > implicit conventions
• Predictable patterns > clever shortcuts
• Four layers > three layers (when the fourth adds semantic value)

Example:

# Good: Four clear layers
nodespec dev app add my-cli

# Not optimal: Ambiguous grouping
nodespec create app my-cli  # "create" could be role or action

Principle 7: Cucumber BDD Integration

Feature files follow the same hierarchical structure.

apps/cli/features/
└── [role]/              # Responsibility
    └── [domain]/        # Workspace
        └── [action]/    # Operation
            └── [action].feature

Why:

• Feature files document the CLI behavior
• Structure mirrors command structure
• Living documentation aligned with implementation

Principle 8: Consistency Across Roles

Same action means same behavior across different domains.

• `add` always creates a new instance
• `list` always shows available instances
• `remove` always deletes an instance
• `validate` always checks correctness

Why:

• Predictable behavior reduces cognitive load
• AI can transfer knowledge across domains
• Users/AI learn the pattern once, apply everywhere

---

Implementation Guidelines

These principles are foundational. Implementation details (specific commands, arguments, flags) should:

1. Follow these principles
2. Be decided during actual implementation
3. Be documented in feature files
4. Evolve based on real usage

Related Issues:

• Three-layer CLI command structure: optimized for AI pattern recognition #11 - Original CLI structure discussion
• Redesign CLI command structure: from concept-based to role-based domains #10 - Role-based domain exploration (closed, superseded)
• Build NodeSpec CLI with real-world project: DeepracticeAccount #1 - Implementation strategy (dogfooding)