Designing an Inspectable AI Development Workflow

Begin with a specific command

The public CLI has three commands: explain, fix, and gen-api. Each gives the request a narrower purpose than an open-ended chat session. The command and target file become explicit inputs that can be inspected before a model call.

• explain asks for an explanation of a file.
• fix asks for suggested changes in a defined Markdown format.
• gen-api asks for an API draft from a requirement file.

Separate orchestration from the prompt

The AgentOrchestrator coordinates file access, prompt selection, the model call, and optional output writing. PromptRegistry holds command-specific instructions. This separation gives a reader concrete places to inspect when the result is unexpected: the input, the chosen prompt, or the returned content.

Follow the request through the trace

The orchestrator records file reads, a directory summary, the selected prompt template, the model call, and output writing when requested. Together, these events show the path a request takes through the program and give a reviewer places to investigate an unexpected result.

• The directory summary appears in the trace.
• The prompt-building call receives the request and target-file content.
• Model-call and output-writing events show how the response moves through the workflow.

Make file operations easy to inspect

The file tool handles local reads, writes, and directory listings. Count and depth limits keep listings small enough to inspect. Keeping file access in a separate tool gives the workflow a clear place to review its path handling and output behavior.

What I would verify before expanding the workflow

The next useful question is whether a result can be reviewed against the original request. A proposed fix needs a check of the behavior it changes. An API draft needs a review of its assumptions and error cases. I would use the trace to connect each proposed result to the inputs and steps that produced it.

• Did the workflow use the intended input file and command?
• Does the output distinguish a proposed change from an applied change?
• What check would confirm that the result meets the request?
• If a dependency fails, can the caller distinguish failure from a useful result?

Current status and limits

DevAgent remains experimental. This note describes the linked source, without a new runtime test or model-quality benchmark. Traces expose workflow steps, but do not prove model correctness or comprehensive repository understanding. File operations use local paths; listing limits do not provide a verified security sandbox.