Skip to main content

Write Feature Context

Use when asked to create, update, or register feature context docs under .agents/references/features from PRDs, Figma, code diffs, touched files, QA findings, or repeated product-domain knowledge.

Source: .agents/skills/write-feature-context/SKILL.md

Metadata​

  • name: write-feature-context

Content​

Write Feature Context

Use this skill to turn feature knowledge into durable repo context that future agents can load without the user repeating the same PRD, Figma, QA, or code history.

Feature context files are prompt context, not product specs. They should orient future agents and still require live code inspection before edits.

Workflow​

  1. Load the baseline context:

    • Read AGENTS.md, .agents/skills/feature-context/SKILL.md, and .agents/references/features/_template.md.
    • Read relevant .agents/rules/*.mdc and coding standards for the feature area.
    • If the user provides PRD, Lark, Figma, browser, QA doc, or issue links, inspect those sources with the appropriate skill/tool before writing.

  2. Inspect live code:

    • Follow .agents/references/coding-standard/codebase-memory-guidance.md and resolve/index the exact current worktree before discovery.
    • Use get_architecture, search_graph, and trace_path to identify durable entrypoints, consumers, data flow, and tests. Resolve exact symbols before using get_code_snippet.
    • Use search_code for source literals/test patterns and rg/find for non-code or insufficient graph results; record fallback searches in the reference only when they remain useful.
    • Read every route, component, hook, service, and utility the user mentions or that the search shows as central to the feature.
    • Check git diff when the request is based on recent work, but do not rely on diff alone; inspect surrounding source.

  3. Choose where the context belongs:

    • Update an existing .agents/references/features/*.md when the domain already exists.
    • Create a new focused file from _template.md when the feature has durable routes, services, workflows, or recurring gotchas that do not fit an existing pack.
    • Keep broad domains broad and focused domains focused. Do not bury a large workflow in an unrelated reference just because it touches that area.

  4. Write the feature reference:

    • Cover purpose, user-facing workflows, key entrypoints, data flow/service boundaries, conventions/gotchas, related standards, useful graph queries/searches, and update triggers.
    • Be detailed but concise. Prefer concrete file paths, query params, service names, state contracts, and redirect rules over general product prose.
    • Include PRD/Figma-derived behavior only after checking it against live code or clearly marking it as a product requirement.
    • Capture durable gotchas from the work: loading states, redirects, modal handoffs, upload failure behavior, stale state risks, service error handling, permissions, and checkout/payment return flows.
    • Do not include temporary branch notes, one-off debugging transcripts, credentials, screenshots, or long copied PRD/Figma text.

  5. Register discovery:

    • If a new feature file is created, add it to the Domain Selection table in .agents/skills/feature-context/SKILL.md.
    • Use trigger terms future agents will actually see: route names, component names, product names, service names, query params, and common user wording.

  6. Sync and clean:

    • Run bun run sync-agents after editing .agents/.
    • Remove temporary notes, exports, screenshots, or scratch files created only for writing the feature context unless the user explicitly asked to keep them.
    • Do not commit or push unless the user explicitly asks.

Quality Bar​

  • The context must be useful to an agent that has never seen the original thread.
  • The doc must point future agents to the right files and searches quickly.
  • The doc must avoid pretending to be the source of truth when live code, PRD, Figma, Apifox, or backend contracts can differ.
  • The doc should make recurring mistakes harder: mention exact state contracts, route/query behavior, service response patterns, and UX invariants.

Verification​

Run:

rtk git diff --check -- .agents/skills .agents/references/features
rtk rg -n "[[:blank:]]$" .agents/skills .agents/references/features

Also verify:

  • New feature references exist in .agents/references/features/.
  • Mirrored files exist under .agent/, .codex/, .cursor/, and .claude/ after bun run sync-agents.
  • feature-context/SKILL.md includes the new reference when one was created.