Eigma
EN 中 DE
Coding Agents From First Principles 打开 Eigma
目录 Anti-patterns in a project brief

Workspace setup

Anti-patterns in a project brief

A brief's failures cluster around one avoidable habit: keeping text that does not earn its place. Claude Code's guidance asks of each line whether removing it would cause a mistake, and says to cut it if not1. The exclusion list that follows is concrete: anything derivable from reading the code, standard language conventions, detailed API documentation that could be linked instead, information that changes often, tutorials, file-by-file descriptions, and self-evident advice such as writing clean code1. What belongs is the complement: commands that cannot be guessed, style rules that differ from the defaults, test instructions, repository etiquette, architectural decisions, environment quirks and known gotchas1.

Other anti-patterns are documented on their own terms, not as more wasted context. Emphasis dilutes: the documentation reserves markers such as IMPORTANT for a single skipped instruction, because "If you emphasize many lines, none of them stands out"1. Contradiction is another documented anti-pattern: two rules that conflict may be resolved arbitrarily, which is why the documentation tells you to review root, nested and rule files for conflicts2. Anthropic's context-engineering post names the remaining two ends of the spectrum, brittle hardcoded logic on one side and vague guidance that gives no concrete signal on the other, with the target being the minimal set of information that fully outlines the expected behaviour3.

A useful diagnostic comes with it. If a rule keeps being ignored, the documentation's first hypothesis is that the file is too long and the rule is getting lost; if the agent asks something the brief already answers, the phrasing is ambiguous1. Splitting the file into imports does not help with length, because imported files still load at launch; only rules scoped to a path glob actually cut startup context2.

The boundary is evidence. No source found for this volume quantifies the adherence loss from an over-long brief, so the length guidance is widely recommended but not measured. The published targets differ across tools that serve different purposes, and their relative currency cannot be established: Claude Code documents a target under 200 lines2, Cursor says to keep rules under 500 lines4, and GitHub's constraint for repository-wide instructions generated via the Copilot agent caps them by pages and forbids task-specific content5. Advice you may have heard, such as banning persona or tone instructions, is left out here because no supporting source was found in the material fetched for this volume.

参考文献

  1. [1]Claude Code best practices
  2. [2]Claude Code memory documentation
  3. [3]Effective context engineering for AI agents
  4. [4]Cursor rules documentation
  5. [5]GitHub Copilot repository instructions
测验

  1. In Claude Code, splitting an over-long brief into @path imported files does what to the context loaded at session start?

    • Leaves it unchanged
    • Cuts it until a matching file is read
    • Cuts it by the size of the imported files

    Imported files still load at launch, so splitting the brief reorganises it without shrinking startup context. Only rules scoped to a path glob actually cut what loads.

  2. A line the agent already honours without being told is a candidate for deletion from the brief.

    • True
    • False

    The documented test asks of each line whether removing it would cause a mistake, and to cut it if not. None of the sources fetched for this volume quantifies what an over-long brief costs in adherence.

评论

还没有评论，来说第一句吧。