Supervisor's Language

– How to design a good prompt?

1. Introduction

While producing a lecture for Claude Code, I generated, modified, and tested various source codes for explanation purposes. In the pre-AI era, spending a considerable amount of time thinking and tweaking was a daily routine to create code for practice, but now with just a few words of prompts, I can generate the desired code, functional code, and code that passes test cases all at once in a matter of minutes. Each time, I felt that I had transitioned from a code creator to a code validator.
Furthermore, I realized that it is crucial to validate the generated code from various perspectives in AI collaboration and that I revisited the universal considerations of what to think about and prompt when generating the initial code.
While configuring the bulletin board example, I prompted the following.

“게시글에 댓글 기능을 추가해줘.”

The results came out within minutes. The Comment entity was created, and Service, Controller, and JPA-based Repository were built, along with the display of the comment list on the screen created with React. However, while viewing the results screen and source code, various questions emerged from the prompts made thoughtlessly.
‘Is it possible to reply to comments?’
‘Is deletion soft or hard?’
‘Can only the author delete it? What about the administrator?’
‘How does paging work?’
Although various questions arose, the AI didn't ask any of them while executing the tasks. Upon reflection, my prompt was at the level of hints rather than requirements, which led to the results obtained. Through similar experiences, I began to contemplate what 'precise prompting' truly means, what elements distinguish it, and how it can be made into a repeatable procedure.

2. Treating prompts as requirement specifications

Ambiguous requirements create ambiguous systems. In requirements engineering, the quality of requirements is assessed based on clarity, completeness, verifiability, and consistency. These four criteria apply directly to prompts as well. The prompt itself conveys our requirements to the AI.

The difference lies in speed. When conveying incomplete requirements to a person, questions naturally arise, such as “Is a reply to comments necessary?” or “What method should we use for deletion?” This process is precisely the refinement of requirements. However, the AI does not ask questions. Instead, it fills in the most plausible defaults and produces immediate results. Not asking questions equates to hiding gaps in the requirements.

To minimize the questioning process resulting from ambiguous prompts, we must bring this questioning process forward to the prompt writing stage. When delegating the blank spaces that were filled through conversations with fellow developers to AI, they must be filled in advance at the time of request. This is why prompts should be treated not merely as instructions but as requirement specifications.

3. Four Considerations for Precision Prompting

I've organized four considerations for precision prompting. Each point is not independent and complements each other.

• Boundary of the Output
  The first thing to clarify is what to create and what not to create. The command 'comment feature' can include various meanings such as replies, likes, reports, sorting options, and notification integration. If boundaries are not set, the AI will set them itself, typically following the most common implementation cases. These boundaries are determined independently of the project's context and are likely to differ from actual requirements.
  Specifying boundaries does not reduce functionality. It is about delineating the scope of this prompt from the next one. This distinction also clarifies the review of the output.

• Relationship with Existing Systems
  The second consideration is to clarify how this feature aligns with the structure of existing programs. This includes aspects like the authentication method of this bulletin board project, the structure of the post entity, and the response format of existing APIs. The AI has the capability to index the entire project and autonomously locate and analyze relevant files, but this ability only extends to understanding how the code is connected. It cannot infer the design intentions behind the program.
  Therefore, outlining the relationship with existing systems in the prompt is not about broadening the AI's exploration scope but rather preventing the AI from generating results based on incorrect assumptions.

• Criteria for Delegation
  The third consideration is to distinguish between areas where the AI can make judgments on its own and areas that developers must explicitly specify. For example, making clear distinctions in the delegation of authority like 'set the deletion policy to soft delete, and suggest the paging method on your own.'
  This distinction is crucial because it directly relates to the cognitive debt and intention debt discussed in previous posts. If a developer delegates a judgment that must be defined (like deletion policies and ranges of authority, which are closely related to business rules) to the AI, the basis for that decision remains only in the code without any documentation. Conversely, if the developer specifies areas where the AI can make judgments (like implementation style, internal method separation), it leads to spending a lot of time on prompt creation. Setting the criteria for delegation ultimately defines where the supervisor's decisions end and the executor's discretion begins.

• Validation Methods
  Finally, the last point is to determine how to verify the results at the request stage. By requesting, 'Please also create a test to check if a 403 is returned when a user attempts to delete rather than the author,' the AI will structure the verification criteria simultaneously with the implementation. Defining the validation method during the post-production phase versus at the request stage results in entirely different outcomes.

These four points can be considered the first gateway to preventing technical debt, cognitive debt, and intention debt. When the boundaries and criteria for delegation are explicitly outlined at the prompt suggestion stage, that record itself becomes a trace of the implementation intention that can be referenced later.

4. Prompt Redesign Process

Here are the differences when redesigning an ambiguous prompt.

The difference between the two prompts is not in length, but in the clarity of delineation between delegation and scope. Areas that can be safely left to the AI, such as code style or the detailed structure of service layers, have been left to its discretion, while only aspects that are directly related to business rules, such as deletion policies, scope of authority, and page sizes, have been specified explicitly. This distinction significantly reduced the time spent reviewing results and allowed us to move to the next step without re-requesting.

5. Prompt Design Checklist

Based on this experience, I have compiled questions to consider before drafting prompts.

• What are the potential failure points of this request?
  (Anticipating issues that may be discovered after results are produced.)

• What parts can the AI decide for itself, and what parts must I define?
  (Business rule-related aspects are not delegated.)

• Have I organized how the new functionality will align with the existing structure?
  (Clarifying relationships such as authentication and data models.)

• Have I considered how to validate the results and included that in the request?
  (Verification criteria will be available alongside the deliverable.)

6. Finally

I believe the key to a good prompt is clear boundaries and a record of delegation. AI does not set the boundaries of the final result and cannot make judgments on which decisions the developer should make. These judgments are solely the responsibility of the developer making the request.
In the end, training the supervisor's language is the process of creating prompts while reflecting on four questions every time faced with a new request: the boundaries of the output, the relationship with existing systems, the criteria for delegation, and the method of verification.

Jin