Should expert-recommended writing styles be directly written into AGENTS.md?

Before writing style requirements, clarify who is reading the output?

When preparing to modify project instructions, first list common readers and their tasks: maintainers need to locate changes, new members need to understand the background, and decision-makers need to know the results and impact. Write a reading goal for your primary current reader, such as being able to find the modification location and run checks after reading the instructions, to help judge whether the expression requirements are helpful.

The same project may require several different outputs. Short progress updates are suitable for quickly understanding current status, operational instructions need to clarify steps, and problem analysis must retain judgment basis. Let each output correspond to its own goal and structure, reducing ambiguity caused by using a single vague style requirement to cover all tasks.

How to turn a preferred style into verifiable requirements?

Write preferences as specific actions, such as providing current conclusions first, then explaining basis and next steps; when encountering unfamiliar terms, add a sentence defining them within the task context. Test with material you can judge yourself, ask readers to point out where guessing is still needed, and refine requirements based on feedback.

Which requirements are suitable to keep as long-term instructions?

Start by retaining requirements applicable across multiple common tasks, such as project languages, required check explanations upon delivery, and existing documentation organization methods. Preferences valid only for specific demos or reader types should be added to individual tasks, facilitating later understanding of usage conditions by new members.

For every new requirement, first read existing instructions to identify repetitions, ambiguities, or conflicts, then consolidate them into clearer descriptions. Test with a familiar task to confirm it resolves previous reading issues. This discussion concerns instruction organization methods and does not infer the loading scope or priority of AGENTS.md and CLAUDE.md across various tools based on summaries.

When should you adjust or remove a specific expression preference?

If readers frequently need to ask for missing background information or if operational instructions cannot be executed directly, return to specific examples to identify which requirement caused ambiguity. Adjust only the relevant parts each time, keeping both pre- and post-adjustment outputs so the team can explain why changes were made. When readers or tasks change, re-evaluate whether the original preferences remain appropriate.

Turn the discussion into a checkable task

Write two versions of the same three-step procedure with identical facts and limits, then ask unfamiliar readers to explain the next action. Record misunderstandings rather than asking only which reads better. Omitting “test accounts only” during simplification is an error. No readers or A/B experiment were recruited here; this is a checkable reading task.