{"content_id":"vduimuvis9","slug":"claude-code-prompt-six-principles-and-templates","locale":"en","schema_type":"HowTo","category":"tutorial","category_name":"Tutorial","title":"6 Prompting Principles for Improving Claude Code Output Quality","summary":"Learn how to structure and communicate context, output contracts, exception handling, and validation criteria instead of simply asking Claude Code to generate code. It also provides prompt templates you can immediately apply to new agent development, feature additions, and bug fixes.","sponsorship_disclosure":null,"author":{"name":"Injoys Editorial Team","url":"https://injoys.com/ko/about"},"key_points":["1. Before starting the task, document the user context, problem to solve, success criteria, and technical constraints in a single document.","2. Specify the deliverable's file structure, data format, permitted scope, and completion criteria in a concrete output contract.","3. Define foreseeable exceptions, such as external API failures, empty results, duplicate data, and authentication errors, along with response policies.","4. Divide the work into planning review, minimum viable implementation, automated testing, and feature expansion, and review the results at each stage.","5. Instead of making vague rework requests, provide failure cases and measurable improvement goals, then validate against the final acceptance criteria."],"content_markdown":"Coding agents such as Claude Code are not merely tools that generate snippets of code; they are working environments that can explore repositories, modify multiple files, and run tests and commands. Therefore, the quality of the result depends less on how plausible the wording sounds and more on **how clearly the scope of work and validation methods are defined**.\n\nA good prompt is not a lengthy explanation but an actionable work specification. It should communicate not only what to build, but also why it is needed, which conditions must be followed, how failures should be handled, and what must pass for the work to be considered complete.\n\n## First Distinguish Between the Prompt and the Execution Environment\n\nVibe coding is a collaborative approach in which intent is communicated in natural language and an AI agent handles the implementation. However, the fact that a request was made in natural language does not guarantee code accuracy or operational stability.\n\nThe following elements work together in a Claude Code task.\n\n| Element | Role | What to Confirm in the Prompt |\n|---|---|---|\n| User request | Communicates the goal and scope of changes | Purpose, priorities, prohibitions |\n| Repository context | Provides the existing structure and rules | Framework, execution commands, related files |\n| `CLAUDE.md` | Provides project instructions that are applied repeatedly | Coding rules, testing methods, directory conventions |\n| Tool permissions | Controls the permitted scope of file modifications and command execution | Commands that may be run and tasks requiring prior confirmation |\n| External connections | Provide access to APIs, databases, MCP servers, and more | Authentication method, trust boundaries, failure policy |\n| Validation procedure | Determines whether the result meets the requirements | Tests, static analysis, manual checks |\n\nWriting a good prompt alone does not solve every problem. For example, Claude Code can create scheduled-execution code, but running a task even while a computer is turned off requires a separate server, CI service, or operating system scheduler. Email delivery also cannot be completed without actual provider credentials and sending permissions.\n\n## Principle 1. Explain the Background, Purpose, and Constraints First\n\nIf you provide only the name of the desired result, such as `Build me a news collection agent`, the agent must guess the users, data sources, execution environment, and success criteria. Even for the same news collector, a business development manager, investor, and university newspaper editor will need different sources and classification criteria.\n\n### Insufficient Request\n\n```text\nBuild me an AI news collection agent.\n```\n\n### Improved Request\n\n```text\nI am a business development manager at an IT startup.\nBefore starting work each day, I want to quickly review news in the AI,\ncloud, and fintech sectors that could affect business partnerships or product strategy.\n\nGoals:\n- Collect recent article candidates for each specified keyword.\n- Remove articles with the same URL and duplicates with similar titles.\n- Classify impact as high, medium, or low based on whether\n  a product or partnership decision is required within 3 months.\n- Produce the results as a Korean email briefing.\n\nConstraints:\n- Preserve the current repository's Python version and package management approach.\n- Before adding a new library, explain its necessity and alternatives.\n- Do not record API keys or email passwords in code or logs.\n- Generate only a preview file before sending an actual email.\n\nFirst investigate the repository structure and how to run it, then propose an implementation plan.\nDo not guess unknown environment details; organize them into a list of questions.\n```\n\nGood background information includes the following four items.\n\n1. **User and usage context:** Who will use it, when, and for what decision\n2. **Goal:** What problem must be solved, rather than simply what code must be written\n3. **Constraints:** Which technologies, security rules, cost limits, or time limits must be maintained\n4. **Non-goals:** Which features are explicitly excluded from this change\n\nStating non-goals prevents the scope from expanding indefinitely. For example, defining that `Scheduled execution and actual email delivery are excluded from this phase` allows the collection and classification logic to be validated reliably first.\n\n## Principle 2. Turn the Desired Output Format into an Output Contract\n\n`Send it as a nicely formatted email` can be interpreted differently by each person. Rather than showing only an example, define the required fields, allowed values, handling of missing data, and sort order together.\n\n```text\nEmail subject:\n[News Briefing] {YYYY-MM-DD} Today's Top News\n\nArticle format in the body:\n1. {Title}\nSummary: {1–2 sentences in Korean}\nImpact: {High|Medium|Low}\nReason for assessment: {1 sentence}\nSource: {Publisher name}\nLink: {Original article URL}\n\nSorting rules:\n1. Highest impact first\n2. If impact is the same, most recent publication time first\n\nStatistics at the bottom:\n- Total number of articles\n- Number of articles by impact level\n- Keywords with no search results\n\nConstraints:\n- Do not invent figures or claims in the summary that are not in the original article.\n- If the date cannot be verified, do not estimate it; mark it as 'Unable to verify.'\n- Exclude items without links from the final briefing.\n```\n\nIf results must be passed between programs, it is helpful to request a JSON schema or type definition along with a human-readable example.\n\n```json\n{\n  \"title\": \"string\",\n  \"summary\": \"string\",\n  \"impact\": \"high | medium | low\",\n  \"reason\": \"string\",\n  \"source\": \"string\",\n  \"url\": \"absolute URL\",\n  \"published_at\": \"ISO 8601 string | null\"\n}\n```\n\nAn output contract includes not only format but also meaning. If there are no assessment criteria defining what `impact: high` means, the JSON syntax may be correct while the classification results remain inconsistent.\n\n## Principle 3. Specify Exceptional Situations and Recovery Policies\n\nThe quality of production code is revealed more clearly in failure paths than in the normal path. A prompt should state foreseeable failures, whether retries are allowed, when the user should be notified, and which information must not be recorded.\n\n| Exceptional Situation | Example Recommended Policy |\n|---|---|\n| No search results | Skip the keyword and record it in the final statistics |\n| Temporary network error | Retry only a limited number of times at set intervals |\n| Authentication failure | Do not retry; stop immediately and provide instructions to check the configuration |\n| API rate limit | Follow the response's waiting instructions and prohibit infinite retries |\n| Duplicate articles | Remove them based on normalized URLs and title similarity |\n| Malformed data | Preserve the original and isolate only the affected item |\n| Email delivery failure | If it still fails after retries, send an alternative notification or record a failure status |\n| Partial success | Report successful results separately from failed items |\n\nYou can request specific policies as follows.\n\n```text\nTreat network timeouts as retryable errors.\nWait between retries, and if the maximum number is exceeded,\nmark only that source as failed.\nStop immediately for authentication errors and invalid requests,\nbecause repeating them will not resolve the problem.\n\nFor every error log, record the time, task stage, source, and error type,\nbut do not record API keys, full email addresses, authentication headers,\nor full article bodies.\nUse process exit statuses to distinguish complete success, partial success,\nand complete failure.\n```\n\nValues such as `retry three times` or `wait 5 seconds` are not universally correct. They must be determined within the project based on the external service's official limits, the urgency of the task, and the risk of duplicate execution. Tasks with side effects, such as payments or message delivery, may be processed more than once if automatically retried without an idempotency guarantee.\n\n## Principle 4. Develop Incrementally in the Order of Plan, Minimum Implementation, and Validation\n\nConnecting multiple external services and automated execution all at once makes it difficult to isolate the cause of an error. Dividing the implementation into small validation units allows the inputs and outputs of each stage to be checked.\n\n### Recommended Sequence\n\n1. Investigate the repository structure, related files, and execution commands.\n2. Have the agent present a plan and the files that will be affected before changing code.\n3. Implement collection using one keyword and fixed sample data.\n4. Test deduplication and impact classification separately.\n5. Validate the email with a local preview instead of actual delivery.\n6. Add actual provider integration and scheduled execution after the tests pass.\n\nThe first request can be limited as follows.\n\n```text\nPerform only phase 1 for now.\nInvestigate the repository and report the following:\n- The current application's entry point\n- Related modules and test files\n- The package management and test commands in use\n- Files that are likely to require changes\n- Questions that must be resolved before implementation\n\nDo not modify any files yet.\n```\n\nAfter reviewing the plan, implement with a narrower scope of changes.\n\n```text\nOf the approved plan, implement only news collection and deduplication.\nDo not add classification, email delivery, or scheduled execution.\nMake it runnable with fixed test data,\nand summarize the modified files and test results at the end.\n```\n\nIf a planning-only mode is available in the Claude Code environment, it can be used during the exploration and design phases. However, a plausible plan does not mean the implementation is correct, so actual tests and code review must follow.\n\n## Principle 5. Provide Feedback with Failure Cases and Numbers\n\nFeedback such as `The result is not very good`, `Performance is slow`, or `The classification is wrong` makes it difficult to determine how to revise the implementation. You must provide the current state, expected state, reproduction input, and the acceptable scope of change.\n\n### Request to Revise Length\n\n```text\nThe current email body is generated at approximately 3,000 characters.\nI want to reduce it to at most 500 characters so it can be read quickly on mobile.\nLimit each article summary to 1–2 sentences and retain the reason for assessment.\nLink the original URL to the title and remove the separate link line.\nKeep the statistics at the bottom.\n```\n\n### Request to Revise Classification Criteria\n\n```text\nOf the 10 test records, 8 were classified as 'high.'\nClassify long-term technology forecasts or general product introductions as 'low.'\nClassify an article as 'high' only when there is specific evidence that a decision\non pricing, product roadmaps, regulatory response, or partnerships must change\nwithin 3 months.\n\nFor the attached cases, A and B should be high, and C should be low.\nRevise the classification rules and add these cases as regression tests.\n```\n\n### Request to Improve Performance\n\n```text\nThe average execution time for the same sample input is currently approximately 45 seconds.\nThe target is at most 30 seconds in the same environment.\nFirst measure the time for each stage and show the bottleneck.\nDo not remove result accuracy or error handling.\nCompare the effects and risks of the improvement options,\nthen apply the smallest change first.\n```\n\nPerformance figures can be compared only when the measurement environment and input data are the same. Do not conclude that performance has improved based on a single execution result; the measurement method, sample, and cache state must also be fixed.\n\n## Principle 6. Use Prompt Templates for Each Type of Task\n\n### New Agent Creation Template\n\n```text\n[Role and Context]\nI am a {profession/role} trying to solve {problem situation}.\nThis result will be used by {user or downstream system}.\n\n[Goal]\n{Result to achieve and success criteria}\n\n[Execution Trigger]\n{Manual execution, event, scheduled time, etc.}\n\n[Input]\n- Data source: {file/API/database}\n- Required fields: {field list}\n- Authentication method: {environment variable or secret management method}\n\n[Processing Logic]\n1. {Step 1}\n2. {Step 2}\n3. {Step 3}\n\n[Output Contract]\n{File format, schema, template, sorting and missing-data rules}\n\n[Exception Handling]\n{Empty results, timeouts, authentication errors, partial failure policy}\n\n[Constraints and Non-goals]\n- Technologies to preserve: {items}\n- Prohibitions: {items}\n- Features excluded from this task: {items}\n\n[Validation]\n- Tests that must pass: {items}\n- Items to include in the completion report: changed files, execution commands, test results, remaining risks\n\nFirst investigate the repository and present an implementation plan.\nDo not guess unknown information; ask questions.\n```\n\n### Existing Feature Addition Template\n\n```text\nAdd {new feature} to the existing {agent or module name}.\nThe new feature must run after {existing stage A} and before {existing stage B}.\n\nDetailed logic:\n- {Conditions and processing rules}\n- {Input/output format}\n- {Behavior on failure}\n\nPreservation requirements:\n- Do not change the existing public interfaces or configuration format.\n- Preserve all existing tests.\n- Do not modify unrelated files.\n\nFirst explain the scope of impact and regression risks,\nthen add tests that preserve the existing behavior before implementing the feature.\n```\n\n### Bug Fix Template\n\n```text\nReproduce the following error and fix its root cause.\n\nFull error message:\n{Error message and stack trace with secrets and personal information removed}\n\nConditions:\n- Execution command: {command}\n- Input: {minimal reproduction input}\n- Environment: {operating system, runtime, relevant versions}\n- Point of occurrence: {which stage}\n\nExpected behavior:\n{Result that should appear under normal operation}\n\nActual behavior:\n{Currently observed result}\n\nRequest:\n1. Reproduce the error first.\n2. Explain the cause based on evidence.\n3. Fix it within the smallest possible scope.\n4. Add a regression test that prevents the same error.\n5. Report the tests run and remaining risks.\n```\n\nWhen pasting error messages, remove sensitive information such as API keys, session tokens, customer data, and internal addresses.\n\n## Complete Example: News Briefing Agent Request\n\nThe following example combines all six principles into a single request.\n\n```text\nI am a business development manager at a SaaS startup.\nI want to review only news about changes in the AI, cloud, and fintech markets\nthat could alter product or partnership decisions within 3 months.\n\nInvestigate the current repository and design a news briefing tool.\nIn the first phase, implement only the functionality that reads sample JSON,\nremoves duplicates, classifies impact, and creates an HTML preview file.\nWeb search, actual email delivery, and scheduled execution are excluded from this phase.\n\nInput fields:\n- title, url, source, published_at, body\n\nProcessing rules:\n- Treat records with the same normalized URL as duplicates.\n- Even if URLs differ, mark articles with similar titles as duplicate candidates.\n- Classify only articles requiring specific changes to pricing, regulatory response,\n  product roadmaps, or partnership decisions within 3 months as 'high' impact.\n- If evidence is insufficient, do not guess a high rating.\n\nOutput:\n- Display the title, 1–2 sentence summary, impact, reason for assessment, source, and URL.\n- Sort by highest impact first.\n- Display the total count, number of duplicates removed, and count by rating at the bottom.\n\nException handling:\n- Do not exclude items missing required fields; record them in a separate error list.\n- Do not estimate invalid dates; keep them as null.\n- Do not leave full article bodies or authentication information in logs.\n\nValidation:\n- Test normal input, empty input, duplicate URLs, invalid dates, and missing required fields.\n- If existing tests are present, they must all pass.\n\nWork sequence:\n1. Investigate the repository structure and related files.\n2. Present the files to be modified and the test plan.\n3. Do not change code until I have reviewed the plan.\n4. After approval, implement the minimum functionality and report the test results.\n```\n\nThis request does not ask for every required feature to be deployed to the production environment at once. Its scope is limited, and the meaning of the output, failure handling, and test cases are defined together, making the result easy to assess.\n\n## Quality Criteria That Are Easy to Miss with Prompts Alone\n\nMany vibe coding guides focus on writing more detailed instructions. However, additional factors that determine actual quality are **verifiability, change control, observability, and security boundaries**.\n\n### 1. Turn Acceptance Criteria into Tests\n\nInstead of saying `Make it work well`, provide paired inputs and expected outputs. Preserve important classification cases as regression tests to confirm that the results remain consistent after subsequent changes.\n\n### 2. Do Not Use the Agent's Self-Assessment as Final Evidence\n\nAn agent saying `Completed` is not the same as the tests passing. Have it report the commands run, test results, changed files, and unresolved risks, and have a person review the diff.\n\n### 3. Minimize Permissions and Secrets\n\nDo not provide access to unnecessary directories, production databases, and deployment credentials all at once. Do not place API keys directly in prompts or repositories; use environment variables or an approved secret management system. Do not grant sensitive repository access to MCP servers or scripts of unknown origin.\n\n### 4. Require Observable Code\n\nFor automated tasks, retain information needed to identify the cause of failures, such as status by stage, structured errors, execution time, and number of records processed. Remove authentication information and personal information from logs.\n\n### 5. Make Changes Reversible\n\nDo not mix unrelated refactoring and feature additions into the same change. Reviewing diffs in small units and recording them in version control makes it easier to isolate and revert incorrect changes.\n\n## Claude Code Project Operation Tips\n\n- Record recurring project rules briefly and specifically in `CLAUDE.md`.\n- Provide build, test, and lint commands in a form that can actually be executed.\n- Do not place secrets, one-off error logs, or lengthy reference documents in `CLAUDE.md`.\n- Before large-scale changes, have the agent investigate related files and dependencies first.\n- When adding a new package, review its necessity, license, and maintenance risks.\n- Do not automatically approve dangerous deletion, deployment, or data modification commands.\n- Before connecting an external API or MCP, confirm where the data will be transmitted.\n- At completion, have the agent summarize changed files, execution commands, test results, and remaining limitations.\n\n## Pre-Submission Checklist\n\n- [ ] Are the user and usage context explained?\n- [ ] Are goals and non-goals separated?\n- [ ] Are existing technologies and prohibited changes specified?\n- [ ] Are the input data and output format defined?\n- [ ] Are the meanings of classification values and status values explained?\n- [ ] Are there policies for empty results, authentication failures, timeouts, and partial failures?\n- [ ] Are planning and implementation separated into stages?\n- [ ] Are there tests for normal, boundary, and failure cases?\n- [ ] Are secrets and personal information excluded from prompts and logs?\n- [ ] Have you requested a diff and execution evidence for human review?\n\nThe key to a good Claude Code prompt is not writing a long command. It is reducing what the agent must guess and enabling a third party to reproduce and assess whether the result is correct.","content_html":"\u003cp\u003eCoding agents such as Claude Code are not merely tools that generate snippets of code; they are working environments that can explore repositories, modify multiple files, and run tests and commands. Therefore, the quality of the result depends less on how plausible the wording sounds and more on \u003cstrong\u003ehow clearly the scope of work and validation methods are defined\u003c/strong\u003e.\u003c/p\u003e\n\u003cp\u003eA good prompt is not a lengthy explanation but an actionable work specification. It should communicate not only what to build, but also why it is needed, which conditions must be followed, how failures should be handled, and what must pass for the work to be considered complete.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#first-distinguish-between-the-prompt-and-the-execution-environment\" class=\"anchor\" id=\"first-distinguish-between-the-prompt-and-the-execution-environment\"\u003e\u003c/a\u003eFirst Distinguish Between the Prompt and the Execution Environment\u003c/h2\u003e\n\u003cp\u003eVibe coding is a collaborative approach in which intent is communicated in natural language and an AI agent handles the implementation. However, the fact that a request was made in natural language does not guarantee code accuracy or operational stability.\u003c/p\u003e\n\u003cp\u003eThe following elements work together in a Claude Code task.\u003c/p\u003e\n\u003cdiv class=\"overflow-x-auto\"\u003e\u003ctable\u003e\n\u003cthead\u003e\n\u003ctr\u003e\n\u003cth\u003eElement\u003c/th\u003e\n\u003cth\u003eRole\u003c/th\u003e\n\u003cth\u003eWhat to Confirm in the Prompt\u003c/th\u003e\n\u003c/tr\u003e\n\u003c/thead\u003e\n\u003ctbody\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Element\"\u003eUser request\u003c/td\u003e\n\u003ctd data-label=\"Role\"\u003eCommunicates the goal and scope of changes\u003c/td\u003e\n\u003ctd data-label=\"What to Confirm in the Prompt\"\u003ePurpose, priorities, prohibitions\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Element\"\u003eRepository context\u003c/td\u003e\n\u003ctd data-label=\"Role\"\u003eProvides the existing structure and rules\u003c/td\u003e\n\u003ctd data-label=\"What to Confirm in the Prompt\"\u003eFramework, execution commands, related files\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Element\"\u003e\u003ccode\u003eCLAUDE.md\u003c/code\u003e\u003c/td\u003e\n\u003ctd data-label=\"Role\"\u003eProvides project instructions that are applied repeatedly\u003c/td\u003e\n\u003ctd data-label=\"What to Confirm in the Prompt\"\u003eCoding rules, testing methods, directory conventions\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Element\"\u003eTool permissions\u003c/td\u003e\n\u003ctd data-label=\"Role\"\u003eControls the permitted scope of file modifications and command execution\u003c/td\u003e\n\u003ctd data-label=\"What to Confirm in the Prompt\"\u003eCommands that may be run and tasks requiring prior confirmation\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Element\"\u003eExternal connections\u003c/td\u003e\n\u003ctd data-label=\"Role\"\u003eProvide access to APIs, databases, MCP servers, and more\u003c/td\u003e\n\u003ctd data-label=\"What to Confirm in the Prompt\"\u003eAuthentication method, trust boundaries, failure policy\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Element\"\u003eValidation procedure\u003c/td\u003e\n\u003ctd data-label=\"Role\"\u003eDetermines whether the result meets the requirements\u003c/td\u003e\n\u003ctd data-label=\"What to Confirm in the Prompt\"\u003eTests, static analysis, manual checks\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\u003c/div\u003e\n\u003cp\u003eWriting a good prompt alone does not solve every problem. For example, Claude Code can create scheduled-execution code, but running a task even while a computer is turned off requires a separate server, CI service, or operating system scheduler. Email delivery also cannot be completed without actual provider credentials and sending permissions.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#principle-1-explain-the-background-purpose-and-constraints-first\" class=\"anchor\" id=\"principle-1-explain-the-background-purpose-and-constraints-first\"\u003e\u003c/a\u003ePrinciple 1. Explain the Background, Purpose, and Constraints First\u003c/h2\u003e\n\u003cp\u003eIf you provide only the name of the desired result, such as \u003ccode\u003eBuild me a news collection agent\u003c/code\u003e, the agent must guess the users, data sources, execution environment, and success criteria. Even for the same news collector, a business development manager, investor, and university newspaper editor will need different sources and classification criteria.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#insufficient-request\" class=\"anchor\" id=\"insufficient-request\"\u003e\u003c/a\u003eInsufficient Request\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eBuild me an AI news collection agent.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#improved-request\" class=\"anchor\" id=\"improved-request\"\u003e\u003c/a\u003eImproved Request\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eI am a business development manager at an IT startup.\n\u003c/span\u003e\u003cspan\u003eBefore starting work each day, I want to quickly review news in the AI,\n\u003c/span\u003e\u003cspan\u003ecloud, and fintech sectors that could affect business partnerships or product strategy.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eGoals:\n\u003c/span\u003e\u003cspan\u003e- Collect recent article candidates for each specified keyword.\n\u003c/span\u003e\u003cspan\u003e- Remove articles with the same URL and duplicates with similar titles.\n\u003c/span\u003e\u003cspan\u003e- Classify impact as high, medium, or low based on whether\n\u003c/span\u003e\u003cspan\u003e  a product or partnership decision is required within 3 months.\n\u003c/span\u003e\u003cspan\u003e- Produce the results as a Korean email briefing.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eConstraints:\n\u003c/span\u003e\u003cspan\u003e- Preserve the current repository's Python version and package management approach.\n\u003c/span\u003e\u003cspan\u003e- Before adding a new library, explain its necessity and alternatives.\n\u003c/span\u003e\u003cspan\u003e- Do not record API keys or email passwords in code or logs.\n\u003c/span\u003e\u003cspan\u003e- Generate only a preview file before sending an actual email.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eFirst investigate the repository structure and how to run it, then propose an implementation plan.\n\u003c/span\u003e\u003cspan\u003eDo not guess unknown environment details; organize them into a list of questions.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eGood background information includes the following four items.\u003c/p\u003e\n\u003col\u003e\n\u003cli\u003e\n\u003cstrong\u003eUser and usage context:\u003c/strong\u003e Who will use it, when, and for what decision\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eGoal:\u003c/strong\u003e What problem must be solved, rather than simply what code must be written\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eConstraints:\u003c/strong\u003e Which technologies, security rules, cost limits, or time limits must be maintained\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eNon-goals:\u003c/strong\u003e Which features are explicitly excluded from this change\u003c/li\u003e\n\u003c/ol\u003e\n\u003cp\u003eStating non-goals prevents the scope from expanding indefinitely. For example, defining that \u003ccode\u003eScheduled execution and actual email delivery are excluded from this phase\u003c/code\u003e allows the collection and classification logic to be validated reliably first.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#principle-2-turn-the-desired-output-format-into-an-output-contract\" class=\"anchor\" id=\"principle-2-turn-the-desired-output-format-into-an-output-contract\"\u003e\u003c/a\u003ePrinciple 2. Turn the Desired Output Format into an Output Contract\u003c/h2\u003e\n\u003cp\u003e\u003ccode\u003eSend it as a nicely formatted email\u003c/code\u003e can be interpreted differently by each person. Rather than showing only an example, define the required fields, allowed values, handling of missing data, and sort order together.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eEmail subject:\n\u003c/span\u003e\u003cspan\u003e[News Briefing] {YYYY-MM-DD} Today's Top News\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eArticle format in the body:\n\u003c/span\u003e\u003cspan\u003e1. {Title}\n\u003c/span\u003e\u003cspan\u003eSummary: {1–2 sentences in Korean}\n\u003c/span\u003e\u003cspan\u003eImpact: {High|Medium|Low}\n\u003c/span\u003e\u003cspan\u003eReason for assessment: {1 sentence}\n\u003c/span\u003e\u003cspan\u003eSource: {Publisher name}\n\u003c/span\u003e\u003cspan\u003eLink: {Original article URL}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eSorting rules:\n\u003c/span\u003e\u003cspan\u003e1. Highest impact first\n\u003c/span\u003e\u003cspan\u003e2. If impact is the same, most recent publication time first\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eStatistics at the bottom:\n\u003c/span\u003e\u003cspan\u003e- Total number of articles\n\u003c/span\u003e\u003cspan\u003e- Number of articles by impact level\n\u003c/span\u003e\u003cspan\u003e- Keywords with no search results\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eConstraints:\n\u003c/span\u003e\u003cspan\u003e- Do not invent figures or claims in the summary that are not in the original article.\n\u003c/span\u003e\u003cspan\u003e- If the date cannot be verified, do not estimate it; mark it as 'Unable to verify.'\n\u003c/span\u003e\u003cspan\u003e- Exclude items without links from the final briefing.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eIf results must be passed between programs, it is helpful to request a JSON schema or type definition along with a human-readable example.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e{\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003etitle\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003estring\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003esummary\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003estring\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003eimpact\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003ehigh | medium | low\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003ereason\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003estring\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003esource\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003estring\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003eurl\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003eabsolute URL\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003epublished_at\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003eISO 8601 string | null\u003c/span\u003e\u003cspan\u003e\"\n\u003c/span\u003e\u003cspan\u003e}\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eAn output contract includes not only format but also meaning. If there are no assessment criteria defining what \u003ccode\u003eimpact: high\u003c/code\u003e means, the JSON syntax may be correct while the classification results remain inconsistent.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#principle-3-specify-exceptional-situations-and-recovery-policies\" class=\"anchor\" id=\"principle-3-specify-exceptional-situations-and-recovery-policies\"\u003e\u003c/a\u003ePrinciple 3. Specify Exceptional Situations and Recovery Policies\u003c/h2\u003e\n\u003cp\u003eThe quality of production code is revealed more clearly in failure paths than in the normal path. A prompt should state foreseeable failures, whether retries are allowed, when the user should be notified, and which information must not be recorded.\u003c/p\u003e\n\u003cdiv class=\"overflow-x-auto\"\u003e\u003ctable\u003e\n\u003cthead\u003e\n\u003ctr\u003e\n\u003cth\u003eExceptional Situation\u003c/th\u003e\n\u003cth\u003eExample Recommended Policy\u003c/th\u003e\n\u003c/tr\u003e\n\u003c/thead\u003e\n\u003ctbody\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Exceptional Situation\"\u003eNo search results\u003c/td\u003e\n\u003ctd data-label=\"Example Recommended Policy\"\u003eSkip the keyword and record it in the final statistics\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Exceptional Situation\"\u003eTemporary network error\u003c/td\u003e\n\u003ctd data-label=\"Example Recommended Policy\"\u003eRetry only a limited number of times at set intervals\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Exceptional Situation\"\u003eAuthentication failure\u003c/td\u003e\n\u003ctd data-label=\"Example Recommended Policy\"\u003eDo not retry; stop immediately and provide instructions to check the configuration\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Exceptional Situation\"\u003eAPI rate limit\u003c/td\u003e\n\u003ctd data-label=\"Example Recommended Policy\"\u003eFollow the response's waiting instructions and prohibit infinite retries\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Exceptional Situation\"\u003eDuplicate articles\u003c/td\u003e\n\u003ctd data-label=\"Example Recommended Policy\"\u003eRemove them based on normalized URLs and title similarity\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Exceptional Situation\"\u003eMalformed data\u003c/td\u003e\n\u003ctd data-label=\"Example Recommended Policy\"\u003ePreserve the original and isolate only the affected item\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Exceptional Situation\"\u003eEmail delivery failure\u003c/td\u003e\n\u003ctd data-label=\"Example Recommended Policy\"\u003eIf it still fails after retries, send an alternative notification or record a failure status\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Exceptional Situation\"\u003ePartial success\u003c/td\u003e\n\u003ctd data-label=\"Example Recommended Policy\"\u003eReport successful results separately from failed items\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\u003c/div\u003e\n\u003cp\u003eYou can request specific policies as follows.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eTreat network timeouts as retryable errors.\n\u003c/span\u003e\u003cspan\u003eWait between retries, and if the maximum number is exceeded,\n\u003c/span\u003e\u003cspan\u003emark only that source as failed.\n\u003c/span\u003e\u003cspan\u003eStop immediately for authentication errors and invalid requests,\n\u003c/span\u003e\u003cspan\u003ebecause repeating them will not resolve the problem.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eFor every error log, record the time, task stage, source, and error type,\n\u003c/span\u003e\u003cspan\u003ebut do not record API keys, full email addresses, authentication headers,\n\u003c/span\u003e\u003cspan\u003eor full article bodies.\n\u003c/span\u003e\u003cspan\u003eUse process exit statuses to distinguish complete success, partial success,\n\u003c/span\u003e\u003cspan\u003eand complete failure.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eValues such as \u003ccode\u003eretry three times\u003c/code\u003e or \u003ccode\u003ewait 5 seconds\u003c/code\u003e are not universally correct. They must be determined within the project based on the external service's official limits, the urgency of the task, and the risk of duplicate execution. Tasks with side effects, such as payments or message delivery, may be processed more than once if automatically retried without an idempotency guarantee.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#principle-4-develop-incrementally-in-the-order-of-plan-minimum-implementation-and-validation\" class=\"anchor\" id=\"principle-4-develop-incrementally-in-the-order-of-plan-minimum-implementation-and-validation\"\u003e\u003c/a\u003ePrinciple 4. Develop Incrementally in the Order of Plan, Minimum Implementation, and Validation\u003c/h2\u003e\n\u003cp\u003eConnecting multiple external services and automated execution all at once makes it difficult to isolate the cause of an error. Dividing the implementation into small validation units allows the inputs and outputs of each stage to be checked.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#recommended-sequence\" class=\"anchor\" id=\"recommended-sequence\"\u003e\u003c/a\u003eRecommended Sequence\u003c/h3\u003e\n\u003col\u003e\n\u003cli\u003eInvestigate the repository structure, related files, and execution commands.\u003c/li\u003e\n\u003cli\u003eHave the agent present a plan and the files that will be affected before changing code.\u003c/li\u003e\n\u003cli\u003eImplement collection using one keyword and fixed sample data.\u003c/li\u003e\n\u003cli\u003eTest deduplication and impact classification separately.\u003c/li\u003e\n\u003cli\u003eValidate the email with a local preview instead of actual delivery.\u003c/li\u003e\n\u003cli\u003eAdd actual provider integration and scheduled execution after the tests pass.\u003c/li\u003e\n\u003c/ol\u003e\n\u003cp\u003eThe first request can be limited as follows.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003ePerform only phase 1 for now.\n\u003c/span\u003e\u003cspan\u003eInvestigate the repository and report the following:\n\u003c/span\u003e\u003cspan\u003e- The current application's entry point\n\u003c/span\u003e\u003cspan\u003e- Related modules and test files\n\u003c/span\u003e\u003cspan\u003e- The package management and test commands in use\n\u003c/span\u003e\u003cspan\u003e- Files that are likely to require changes\n\u003c/span\u003e\u003cspan\u003e- Questions that must be resolved before implementation\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eDo not modify any files yet.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eAfter reviewing the plan, implement with a narrower scope of changes.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eOf the approved plan, implement only news collection and deduplication.\n\u003c/span\u003e\u003cspan\u003eDo not add classification, email delivery, or scheduled execution.\n\u003c/span\u003e\u003cspan\u003eMake it runnable with fixed test data,\n\u003c/span\u003e\u003cspan\u003eand summarize the modified files and test results at the end.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eIf a planning-only mode is available in the Claude Code environment, it can be used during the exploration and design phases. However, a plausible plan does not mean the implementation is correct, so actual tests and code review must follow.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#principle-5-provide-feedback-with-failure-cases-and-numbers\" class=\"anchor\" id=\"principle-5-provide-feedback-with-failure-cases-and-numbers\"\u003e\u003c/a\u003ePrinciple 5. Provide Feedback with Failure Cases and Numbers\u003c/h2\u003e\n\u003cp\u003eFeedback such as \u003ccode\u003eThe result is not very good\u003c/code\u003e, \u003ccode\u003ePerformance is slow\u003c/code\u003e, or \u003ccode\u003eThe classification is wrong\u003c/code\u003e makes it difficult to determine how to revise the implementation. You must provide the current state, expected state, reproduction input, and the acceptable scope of change.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#request-to-revise-length\" class=\"anchor\" id=\"request-to-revise-length\"\u003e\u003c/a\u003eRequest to Revise Length\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eThe current email body is generated at approximately 3,000 characters.\n\u003c/span\u003e\u003cspan\u003eI want to reduce it to at most 500 characters so it can be read quickly on mobile.\n\u003c/span\u003e\u003cspan\u003eLimit each article summary to 1–2 sentences and retain the reason for assessment.\n\u003c/span\u003e\u003cspan\u003eLink the original URL to the title and remove the separate link line.\n\u003c/span\u003e\u003cspan\u003eKeep the statistics at the bottom.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#request-to-revise-classification-criteria\" class=\"anchor\" id=\"request-to-revise-classification-criteria\"\u003e\u003c/a\u003eRequest to Revise Classification Criteria\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eOf the 10 test records, 8 were classified as 'high.'\n\u003c/span\u003e\u003cspan\u003eClassify long-term technology forecasts or general product introductions as 'low.'\n\u003c/span\u003e\u003cspan\u003eClassify an article as 'high' only when there is specific evidence that a decision\n\u003c/span\u003e\u003cspan\u003eon pricing, product roadmaps, regulatory response, or partnerships must change\n\u003c/span\u003e\u003cspan\u003ewithin 3 months.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eFor the attached cases, A and B should be high, and C should be low.\n\u003c/span\u003e\u003cspan\u003eRevise the classification rules and add these cases as regression tests.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#request-to-improve-performance\" class=\"anchor\" id=\"request-to-improve-performance\"\u003e\u003c/a\u003eRequest to Improve Performance\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eThe average execution time for the same sample input is currently approximately 45 seconds.\n\u003c/span\u003e\u003cspan\u003eThe target is at most 30 seconds in the same environment.\n\u003c/span\u003e\u003cspan\u003eFirst measure the time for each stage and show the bottleneck.\n\u003c/span\u003e\u003cspan\u003eDo not remove result accuracy or error handling.\n\u003c/span\u003e\u003cspan\u003eCompare the effects and risks of the improvement options,\n\u003c/span\u003e\u003cspan\u003ethen apply the smallest change first.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003ePerformance figures can be compared only when the measurement environment and input data are the same. Do not conclude that performance has improved based on a single execution result; the measurement method, sample, and cache state must also be fixed.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#principle-6-use-prompt-templates-for-each-type-of-task\" class=\"anchor\" id=\"principle-6-use-prompt-templates-for-each-type-of-task\"\u003e\u003c/a\u003ePrinciple 6. Use Prompt Templates for Each Type of Task\u003c/h2\u003e\n\u003ch3\u003e\n\u003ca href=\"#new-agent-creation-template\" class=\"anchor\" id=\"new-agent-creation-template\"\u003e\u003c/a\u003eNew Agent Creation Template\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e[Role and Context]\n\u003c/span\u003e\u003cspan\u003eI am a {profession/role} trying to solve {problem situation}.\n\u003c/span\u003e\u003cspan\u003eThis result will be used by {user or downstream system}.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[Goal]\n\u003c/span\u003e\u003cspan\u003e{Result to achieve and success criteria}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[Execution Trigger]\n\u003c/span\u003e\u003cspan\u003e{Manual execution, event, scheduled time, etc.}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[Input]\n\u003c/span\u003e\u003cspan\u003e- Data source: {file/API/database}\n\u003c/span\u003e\u003cspan\u003e- Required fields: {field list}\n\u003c/span\u003e\u003cspan\u003e- Authentication method: {environment variable or secret management method}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[Processing Logic]\n\u003c/span\u003e\u003cspan\u003e1. {Step 1}\n\u003c/span\u003e\u003cspan\u003e2. {Step 2}\n\u003c/span\u003e\u003cspan\u003e3. {Step 3}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[Output Contract]\n\u003c/span\u003e\u003cspan\u003e{File format, schema, template, sorting and missing-data rules}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[Exception Handling]\n\u003c/span\u003e\u003cspan\u003e{Empty results, timeouts, authentication errors, partial failure policy}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[Constraints and Non-goals]\n\u003c/span\u003e\u003cspan\u003e- Technologies to preserve: {items}\n\u003c/span\u003e\u003cspan\u003e- Prohibitions: {items}\n\u003c/span\u003e\u003cspan\u003e- Features excluded from this task: {items}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[Validation]\n\u003c/span\u003e\u003cspan\u003e- Tests that must pass: {items}\n\u003c/span\u003e\u003cspan\u003e- Items to include in the completion report: changed files, execution commands, test results, remaining risks\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eFirst investigate the repository and present an implementation plan.\n\u003c/span\u003e\u003cspan\u003eDo not guess unknown information; ask questions.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#existing-feature-addition-template\" class=\"anchor\" id=\"existing-feature-addition-template\"\u003e\u003c/a\u003eExisting Feature Addition Template\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eAdd {new feature} to the existing {agent or module name}.\n\u003c/span\u003e\u003cspan\u003eThe new feature must run after {existing stage A} and before {existing stage B}.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eDetailed logic:\n\u003c/span\u003e\u003cspan\u003e- {Conditions and processing rules}\n\u003c/span\u003e\u003cspan\u003e- {Input/output format}\n\u003c/span\u003e\u003cspan\u003e- {Behavior on failure}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003ePreservation requirements:\n\u003c/span\u003e\u003cspan\u003e- Do not change the existing public interfaces or configuration format.\n\u003c/span\u003e\u003cspan\u003e- Preserve all existing tests.\n\u003c/span\u003e\u003cspan\u003e- Do not modify unrelated files.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eFirst explain the scope of impact and regression risks,\n\u003c/span\u003e\u003cspan\u003ethen add tests that preserve the existing behavior before implementing the feature.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#bug-fix-template\" class=\"anchor\" id=\"bug-fix-template\"\u003e\u003c/a\u003eBug Fix Template\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eReproduce the following error and fix its root cause.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eFull error message:\n\u003c/span\u003e\u003cspan\u003e{Error message and stack trace with secrets and personal information removed}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eConditions:\n\u003c/span\u003e\u003cspan\u003e- Execution command: {command}\n\u003c/span\u003e\u003cspan\u003e- Input: {minimal reproduction input}\n\u003c/span\u003e\u003cspan\u003e- Environment: {operating system, runtime, relevant versions}\n\u003c/span\u003e\u003cspan\u003e- Point of occurrence: {which stage}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eExpected behavior:\n\u003c/span\u003e\u003cspan\u003e{Result that should appear under normal operation}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eActual behavior:\n\u003c/span\u003e\u003cspan\u003e{Currently observed result}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eRequest:\n\u003c/span\u003e\u003cspan\u003e1. Reproduce the error first.\n\u003c/span\u003e\u003cspan\u003e2. Explain the cause based on evidence.\n\u003c/span\u003e\u003cspan\u003e3. Fix it within the smallest possible scope.\n\u003c/span\u003e\u003cspan\u003e4. Add a regression test that prevents the same error.\n\u003c/span\u003e\u003cspan\u003e5. Report the tests run and remaining risks.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eWhen pasting error messages, remove sensitive information such as API keys, session tokens, customer data, and internal addresses.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#complete-example-news-briefing-agent-request\" class=\"anchor\" id=\"complete-example-news-briefing-agent-request\"\u003e\u003c/a\u003eComplete Example: News Briefing Agent Request\u003c/h2\u003e\n\u003cp\u003eThe following example combines all six principles into a single request.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eI am a business development manager at a SaaS startup.\n\u003c/span\u003e\u003cspan\u003eI want to review only news about changes in the AI, cloud, and fintech markets\n\u003c/span\u003e\u003cspan\u003ethat could alter product or partnership decisions within 3 months.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eInvestigate the current repository and design a news briefing tool.\n\u003c/span\u003e\u003cspan\u003eIn the first phase, implement only the functionality that reads sample JSON,\n\u003c/span\u003e\u003cspan\u003eremoves duplicates, classifies impact, and creates an HTML preview file.\n\u003c/span\u003e\u003cspan\u003eWeb search, actual email delivery, and scheduled execution are excluded from this phase.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eInput fields:\n\u003c/span\u003e\u003cspan\u003e- title, url, source, published_at, body\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eProcessing rules:\n\u003c/span\u003e\u003cspan\u003e- Treat records with the same normalized URL as duplicates.\n\u003c/span\u003e\u003cspan\u003e- Even if URLs differ, mark articles with similar titles as duplicate candidates.\n\u003c/span\u003e\u003cspan\u003e- Classify only articles requiring specific changes to pricing, regulatory response,\n\u003c/span\u003e\u003cspan\u003e  product roadmaps, or partnership decisions within 3 months as 'high' impact.\n\u003c/span\u003e\u003cspan\u003e- If evidence is insufficient, do not guess a high rating.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eOutput:\n\u003c/span\u003e\u003cspan\u003e- Display the title, 1–2 sentence summary, impact, reason for assessment, source, and URL.\n\u003c/span\u003e\u003cspan\u003e- Sort by highest impact first.\n\u003c/span\u003e\u003cspan\u003e- Display the total count, number of duplicates removed, and count by rating at the bottom.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eException handling:\n\u003c/span\u003e\u003cspan\u003e- Do not exclude items missing required fields; record them in a separate error list.\n\u003c/span\u003e\u003cspan\u003e- Do not estimate invalid dates; keep them as null.\n\u003c/span\u003e\u003cspan\u003e- Do not leave full article bodies or authentication information in logs.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eValidation:\n\u003c/span\u003e\u003cspan\u003e- Test normal input, empty input, duplicate URLs, invalid dates, and missing required fields.\n\u003c/span\u003e\u003cspan\u003e- If existing tests are present, they must all pass.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eWork sequence:\n\u003c/span\u003e\u003cspan\u003e1. Investigate the repository structure and related files.\n\u003c/span\u003e\u003cspan\u003e2. Present the files to be modified and the test plan.\n\u003c/span\u003e\u003cspan\u003e3. Do not change code until I have reviewed the plan.\n\u003c/span\u003e\u003cspan\u003e4. After approval, implement the minimum functionality and report the test results.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eThis request does not ask for every required feature to be deployed to the production environment at once. Its scope is limited, and the meaning of the output, failure handling, and test cases are defined together, making the result easy to assess.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#quality-criteria-that-are-easy-to-miss-with-prompts-alone\" class=\"anchor\" id=\"quality-criteria-that-are-easy-to-miss-with-prompts-alone\"\u003e\u003c/a\u003eQuality Criteria That Are Easy to Miss with Prompts Alone\u003c/h2\u003e\n\u003cp\u003eMany vibe coding guides focus on writing more detailed instructions. However, additional factors that determine actual quality are \u003cstrong\u003everifiability, change control, observability, and security boundaries\u003c/strong\u003e.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#1-turn-acceptance-criteria-into-tests\" class=\"anchor\" id=\"1-turn-acceptance-criteria-into-tests\"\u003e\u003c/a\u003e1. Turn Acceptance Criteria into Tests\u003c/h3\u003e\n\u003cp\u003eInstead of saying \u003ccode\u003eMake it work well\u003c/code\u003e, provide paired inputs and expected outputs. Preserve important classification cases as regression tests to confirm that the results remain consistent after subsequent changes.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#2-do-not-use-the-agents-self-assessment-as-final-evidence\" class=\"anchor\" id=\"2-do-not-use-the-agents-self-assessment-as-final-evidence\"\u003e\u003c/a\u003e2. Do Not Use the Agent's Self-Assessment as Final Evidence\u003c/h3\u003e\n\u003cp\u003eAn agent saying \u003ccode\u003eCompleted\u003c/code\u003e is not the same as the tests passing. Have it report the commands run, test results, changed files, and unresolved risks, and have a person review the diff.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#3-minimize-permissions-and-secrets\" class=\"anchor\" id=\"3-minimize-permissions-and-secrets\"\u003e\u003c/a\u003e3. Minimize Permissions and Secrets\u003c/h3\u003e\n\u003cp\u003eDo not provide access to unnecessary directories, production databases, and deployment credentials all at once. Do not place API keys directly in prompts or repositories; use environment variables or an approved secret management system. Do not grant sensitive repository access to MCP servers or scripts of unknown origin.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#4-require-observable-code\" class=\"anchor\" id=\"4-require-observable-code\"\u003e\u003c/a\u003e4. Require Observable Code\u003c/h3\u003e\n\u003cp\u003eFor automated tasks, retain information needed to identify the cause of failures, such as status by stage, structured errors, execution time, and number of records processed. Remove authentication information and personal information from logs.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#5-make-changes-reversible\" class=\"anchor\" id=\"5-make-changes-reversible\"\u003e\u003c/a\u003e5. Make Changes Reversible\u003c/h3\u003e\n\u003cp\u003eDo not mix unrelated refactoring and feature additions into the same change. Reviewing diffs in small units and recording them in version control makes it easier to isolate and revert incorrect changes.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#claude-code-project-operation-tips\" class=\"anchor\" id=\"claude-code-project-operation-tips\"\u003e\u003c/a\u003eClaude Code Project Operation Tips\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003eRecord recurring project rules briefly and specifically in \u003ccode\u003eCLAUDE.md\u003c/code\u003e.\u003c/li\u003e\n\u003cli\u003eProvide build, test, and lint commands in a form that can actually be executed.\u003c/li\u003e\n\u003cli\u003eDo not place secrets, one-off error logs, or lengthy reference documents in \u003ccode\u003eCLAUDE.md\u003c/code\u003e.\u003c/li\u003e\n\u003cli\u003eBefore large-scale changes, have the agent investigate related files and dependencies first.\u003c/li\u003e\n\u003cli\u003eWhen adding a new package, review its necessity, license, and maintenance risks.\u003c/li\u003e\n\u003cli\u003eDo not automatically approve dangerous deletion, deployment, or data modification commands.\u003c/li\u003e\n\u003cli\u003eBefore connecting an external API or MCP, confirm where the data will be transmitted.\u003c/li\u003e\n\u003cli\u003eAt completion, have the agent summarize changed files, execution commands, test results, and remaining limitations.\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2\u003e\n\u003ca href=\"#pre-submission-checklist\" class=\"anchor\" id=\"pre-submission-checklist\"\u003e\u003c/a\u003ePre-Submission Checklist\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e Are the user and usage context explained?\u003c/li\u003e\n\u003cli\u003e Are goals and non-goals separated?\u003c/li\u003e\n\u003cli\u003e Are existing technologies and prohibited changes specified?\u003c/li\u003e\n\u003cli\u003e Are the input data and output format defined?\u003c/li\u003e\n\u003cli\u003e Are the meanings of classification values and status values explained?\u003c/li\u003e\n\u003cli\u003e Are there policies for empty results, authentication failures, timeouts, and partial failures?\u003c/li\u003e\n\u003cli\u003e Are planning and implementation separated into stages?\u003c/li\u003e\n\u003cli\u003e Are there tests for normal, boundary, and failure cases?\u003c/li\u003e\n\u003cli\u003e Are secrets and personal information excluded from prompts and logs?\u003c/li\u003e\n\u003cli\u003e Have you requested a diff and execution evidence for human review?\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003eThe key to a good Claude Code prompt is not writing a long command. It is reducing what the agent must guess and enabling a third party to reproduce and assess whether the result is correct.\u003c/p\u003e\n","tags":["Prompt Engineering","Harness Engineering","Claude Code","AI Coding","Coding Agent"],"faqs":[{"question":"Are longer Claude Code prompts better?","answer":"What matters more than length is whether the information needed for the task is included in a structured way. Be specific about the background, goals, constraints, output contract, exception handling, and completion criteria, while removing irrelevant explanations and duplicate instructions."},{"question":"Can I ask it to create the entire program from the start?","answer":"This may be possible for a small, standalone tool, but it is safer to develop tasks involving an external API, database, email, and scheduled execution in stages. Reviewing the repository investigation and plan first, then expanding in the order of minimum functionality, testing, and external integrations makes it easier to isolate the causes of failures."},{"question":"Can I skip testing if I use Plan Mode?","answer":"No. Plan Mode is useful for reviewing the structure and approach before making changes, but it does not prove that the actual code is correct. After implementation, you must separately perform automated tests, static analysis, review the changes, and carry out any necessary manual checks."},{"question":"What should I include in CLAUDE.md?","answer":"It is appropriate to include instructions that recur across multiple tasks, such as the project structure, coding conventions, build and test commands, and areas that must not be modified. It is best not to include API keys, passwords, personal information, descriptions of one-off tasks, or excessively long reference materials."},{"question":"What information should I provide when requesting a bug fix?","answer":"You should provide the error message and stack trace with sensitive information removed, the execution command, minimal reproduction input, the relevant environment, and the actual and expected behavior. It is also advisable to request an explanation of the cause, a minimal-scope fix, regression tests, and execution results."},{"question":"Can I provide an API key to Claude Code in a prompt?","answer":"As a rule, you should not directly include actual API keys in prompts or source code. Use approved environment variables or a secrets management system, and ensure that credentials are not exposed in logs or test results."},{"question":"Do I have to specify the number of retries and the wait time in the prompt?","answer":"For operational automation, it is important to distinguish between errors that can be retried and errors that require immediate termination. However, the specific number of retries and wait time should be determined after checking the external service's limits, the urgency of the task, and the risk of duplicate processing, and not every error should be retried unconditionally."},{"question":"How can I tell whether the generated code is complete?","answer":"Assess it against predefined acceptance criteria. Check whether tests for required functionality and edge cases pass, the commands that were run, the files that were changed, and whether performance or security constraints are met, and have a person review the code changes."}],"sources":[{"url":"https://docs.anthropic.com/en/docs/claude-code/overview","title":"Claude Code overview","type":"source"},{"url":"https://www.anthropic.com/engineering/claude-code-best-practices","title":"Claude Code: Best practices for agentic coding","type":"source"},{"url":"https://github.com/anthropics/claude-code","title":"Anthropic Claude Code GitHub repository","type":"source"}],"images":[{"id":845,"url":"https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MTExNTQsInB1ciI6ImJsb2JfaWQifX0=--9f2d2e2c8a61fc294a6019e4807ece297f36e85a/ai-4caeb237.webp","is_representative":true,"generation_method":"ai_photo","license":"ai_generated","mime_type":"image/webp","translations":{"ko":{"alt":"코드와 작업 흐름이 표시된 대형 모니터 앞에서 작업하는 개발자","caption":"개발자가 여러 화면의 코드와 문서를 검토하며 작업하고 있다.","description":null},"en":{"alt":"Developer working at a desk with code and a workflow diagram on a large monitor","caption":"A developer reviews code and documentation across multiple screens.","description":null},"ja":{"alt":"コードとワークフロー図を映した大型モニターの前で作業する開発者","caption":"開発者が複数の画面でコードとドキュメントを確認している。","description":null},"es":{"alt":"Desarrollador trabajando frente a un monitor grande con código y un diagrama de flujo","caption":"Un desarrollador revisa código y documentación en varias pantallas.","description":null},"id":{"alt":"Pengembang bekerja di depan monitor besar yang menampilkan kode dan diagram alur kerja","caption":"Seorang pengembang meninjau kode dan dokumentasi di beberapa layar.","description":null},"pt":{"alt":"Desenvolvedor trabalhando diante de um monitor grande com código e diagrama de fluxo","caption":"Um desenvolvedor analisa código e documentação em várias telas.","description":null},"zh-hant":{"alt":"開發人員在顯示程式碼與工作流程圖的大型螢幕前工作","caption":"開發人員正透過多個螢幕檢視程式碼與文件。","description":null},"de":{"alt":"Entwickler vor einem großen Monitor mit Code und einem Ablaufdiagramm","caption":"Ein Entwickler prüft Code und Dokumentation auf mehreren Bildschirmen.","description":null}}},{"id":846,"url":"https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MTExNjAsInB1ciI6ImJsb2JfaWQifX0=--285d7ecdc8209e07e0fc4eb68085cd8a304b9a81/ai-062b34c5.webp","is_representative":false,"generation_method":"ai_image","license":"ai_generated","mime_type":"image/webp","translations":{"ko":{"alt":"코드 편집기가 열린 노트북과 요구사항, 표, 오류, 버전 관리, 성과 차트를 연결한 개발 워크플로","caption":"체계적인 프롬프트가 코딩 결과물의 검증과 완성도를 높이는 과정을 보여준다.","description":null},"en":{"alt":"Laptop code editor connected to requirements, tables, errors, version control, and performance charts","caption":"The workflow shows how structured prompts support validation and more polished coding results.","description":null},"ja":{"alt":"要件、表、エラー、バージョン管理、成果グラフにつながるコードエディター搭載ノートPC","caption":"構造化されたプロンプトがコードの検証と完成度向上を支える流れを示している。","description":null},"es":{"alt":"Portátil con editor de código conectado a requisitos, tablas, errores, versiones y gráficos de rendimiento","caption":"El flujo muestra cómo los prompts estructurados ayudan a validar y perfeccionar el código.","description":null},"id":{"alt":"Laptop dengan editor kode yang terhubung ke spesifikasi, tabel, galat, kontrol versi, dan grafik kinerja","caption":"Alur ini menunjukkan bagaimana prompt terstruktur membantu validasi dan penyempurnaan hasil kode.","description":null},"pt":{"alt":"Notebook com editor de código ligado a requisitos, tabelas, erros, controle de versão e gráficos de desempenho","caption":"O fluxo mostra como prompts estruturados ajudam a validar e aprimorar os resultados do código.","description":null},"zh-hant":{"alt":"筆電程式碼編輯器連結需求、表格、錯誤、版本控制與成效圖表","caption":"此流程呈現結構化提示如何協助驗證程式碼並提升成果完成度。","description":null},"de":{"alt":"Laptop mit Code-Editor, verbunden mit Anforderungen, Tabellen, Fehlern, Versionskontrolle und Leistungsdiagrammen","caption":"Der Ablauf zeigt, wie strukturierte Prompts die Prüfung und Verfeinerung von Code unterstützen.","description":null}}}],"published_at":"2026-08-23T02:30:01+09:00","updated_at":"2026-08-23T02:30:01+09:00","license":"cc_by","translation_status":"reviewed","available_locales":["ko","en","ja","es"],"data_locales":["ko","en","ja","es","id","pt","zh-hant","de"],"url":"https://injoys.com/en/articles/claude-code-prompt-six-principles-and-templates"}