Answer in 2 sentences
Project instructions describe the stable facts, conventions, boundaries, and checks an assistant needs when working in a particular project. Files such as AGENTS.md and CLAUDE.md can carry that guidance in coding workflows, while shared tone guides and support instructions serve the same purpose for non-coding work.
How do system prompts, project instructions, and task prompts differ?
A system prompt supplies operating instructions at the assistant or application level. Project instructions add context for one repository, workspace, or team. A task prompt describes the specific result you want now, including changing facts and acceptance criteria. These layers answer different questions: how the assistant operates, how this project works, and what this assignment requires.
Do not assume a project file can override every other instruction an assistant receives. File discovery, scope, and precedence depend on the tool and its configuration. Check the environment you actually use before relying on a filename or directory placement. A file that exists but is never loaded cannot influence the work.
A practical split is simple: keep the repository's test command in project instructions, and keep today's bug reproduction in the task. For a support team, keep approved tone rules in shared guidance, and keep the customer's current order details in the individual request.
What should go in AGENTS.md or CLAUDE.md?
Include information a capable new contributor would otherwise have to rediscover. Explain the product in a short paragraph, identify important directories, and give commands that actually work in this repository. State constraints with a reason or a clear boundary so the assistant can apply them when circumstances change.
Useful content includes:
- The project's purpose and the main user journey.
- A small map of source, tests, fixtures, and maintained documentation.
- Setup and validation commands, including the directory where they run.
- Local conventions that differ from obvious framework defaults.
- Areas that require focused review, such as generated files or public interfaces.
- Expected completion evidence, including unresolved checks.
Avoid copying a whole framework manual into the file. The instructions should point to maintained documentation and explain the local exceptions. A short command that has been verified is more useful than a long list of guessed tooling choices.
Which project instruction template can a team copy?
The following is a starting structure for either file. Replace every bracketed field and remove sections that do not apply. The labels are organizational choices, not special syntax that every agent interprets identically.
Project: [Product name] helps [audience] accomplish [main task]. The primary workflow is [brief sequence].
Repository map: [Directory] contains [responsibility]. [Directory] contains [tests or fixtures]. The maintained source for [important fact] is [file].
Setup: From [working directory], run [verified setup command]. Required configuration is documented in [reference]. Use example configuration without inserting secrets into tracked files.
Implementation conventions: Reuse [existing components or patterns]. Preserve [public interface or data behavior]. Explain any new dependency before adding it. Do not edit [generated output]; update [source] instead.
Validation: For [change type], run [verified command]. For [user flow], check [observable behavior]. Report checks that cannot run and the reason.
Boundaries: Stay within the requested scope. Before changing [shared contract], inspect [callers or documentation]. Ask when a missing product decision would change the intended behavior.
Completion: Summarize the resulting behavior, changed files, validation evidence, and remaining limitations.
Keep these instructions specific. “Use good architecture” offers little guidance; “reuse the existing request client so error handling stays consistent” connects a choice to a project requirement.
How should you handle multiple instruction files?
Decide which guidance is shared and which is specific to a tool or directory. If the same rule appears in several places, designate a maintained source and review the copies together. Contradictory validation commands force the assistant to guess and make onboarding harder for humans too.
For a repository with several applications, a root file can explain the directory map while local guidance explains each application's commands. Verify how your chosen tool loads instructions before relying on nested files. Do not invent a universal rule that the nearest file always wins or that every agent reads both filenames automatically.
If you maintain AGENTS.md and CLAUDE.md, avoid filling them with subtly different product policies. Shared facts should agree. Tool-specific guidance should explain its limited context, such as where to find the relevant project documentation, rather than rewrite the entire team's rules.
What belongs in a per-task prompt instead?
Put the current objective, reproduction, affected surface, and acceptance criteria in the task. That prevents an old bug report from becoming a permanent restriction on future work. Link to project guidance when useful, but do not paste every stable rule into each assignment.
Copy this task prompt: Update [specific behavior] in [surface]. Current behavior: [reproduction and observation]. Desired behavior: [observable result]. Read the project instructions and inspect the relevant implementation first. Preserve [nearby behavior]. Defer [out-of-scope work]. Completion requires [checks]. Report assumptions, changed files, and any incomplete validation.
For a larger change, ask for a proposal before implementation. The plan-first prompt guide provides feature, refactor, and investigation templates. Project guidance can define how plans are reviewed without dictating the content of every future plan.
Can project instructions help non-coding teams?
Yes. A team tone guide is project context for writing work. It can identify the audience, preferred vocabulary, approved claims, and review expectations. The purpose is the same as repository guidance: reduce repeated explanation while leaving current facts in the assignment.
Copy this team tone guide: Write for [audience] in plain language. Be direct, respectful, and specific. Prefer short paragraphs and concrete next steps. Preserve names, dates, quantities, and commitments from the source. Avoid invented testimonials, performance claims, or urgency. Use [approved terminology]. If facts are missing, identify the gap rather than filling it with a plausible detail. For each task, follow its requested format and length while preserving essential meaning.
Test the guide on an announcement, a routine reply, and a difficult refusal. If every output sounds identical, loosen the style rules and clarify how tone should adapt to the audience. Consistency should preserve the team's intent without forcing every message into the same greeting and closing.
What should a reusable support macro contain?
Separate the response pattern from the customer's facts. A macro can explain how to acknowledge an issue and request missing information, but it should not turn one case's remedy into a promise for everyone.
Copy this support macro instruction: Draft a reply using the current case details and supplied policy. First acknowledge the customer's specific issue. Then explain the next permitted step. Ask only for information that is missing. Use calm, clear wording and avoid blaming the customer. Do not promise a refund, replacement, delivery date, or response deadline unless the supplied policy authorizes it for this case. If the policy does not answer the request, prepare a short holding reply and identify the question for a human reviewer.
Case input: Customer message: [message]. Confirmed facts: [facts]. Policy excerpt: [approved text]. Information already received: [details]. Allowed next step: [action].
This structure makes the policy dependency visible. Try a case with an order number already supplied and a case without one. A useful macro should ask for the number only in the second case.
Which mistakes make project instructions less useful?
The most common problems are stale commands, contradictory rules, long wish lists, and missing acceptance checks. Another is treating instruction files as a dumping ground for every lesson from one incident. Record a general rule only when it helps future tasks, and include enough context to avoid overapplying it.
Review changes to the guidance alongside changes to tooling or product policy. Ask a teammate to follow the setup steps from the stated directory. If a command no longer works, repair the source rather than telling each assistant a different workaround.
PromptDC is a universal AI assistant whose profiles hold reusable instructions for writing tasks, with Code as one profile. The same stable-versus-current distinction helps when saving a team tone guide: preserve recurring rules and supply each message's facts separately.
FAQ
Are AGENTS.md and CLAUDE.md the same thing?
They can contain similar project guidance, but their loading behavior depends on the agent. Verify support and scope in your working environment rather than assuming interchangeable behavior.
Should I put secrets in project instructions?
No. Reference the approved configuration process. Instructions should explain where configuration belongs without placing credentials in a shared or tracked file.
How long should a project instruction file be?
Use enough detail to remove repeated uncertainty. Keep the core concise and link to maintained references for deeper explanations, especially when those references change independently.
Can I use this approach for a writing team?
Yes. Save audience, tone, approved terminology, and policy boundaries as stable guidance. Supply the actual message, case facts, and desired result with each task.
How do I know the instructions are working?
Check whether the assistant follows the relevant conventions on representative tasks. Verify the file is loaded, then compare actual outputs and validation evidence with the stated requirements.





