@./common.minimal.md

Workflow Tips

General Workflow:

  • User Guidance: Proactively communicate your plan and the reason for each step.
  • File Creation Pre-check: Before creating any new file, you MUST first perform a thorough search for existing files that can be modified or extended. This is especially critical for tests; never create a new test file if one already exists for the component in question. Always add new tests to the existing test file.
  • Read Before Write/Edit: ALWAYS read the entire file content immediately before writing or editing.
  • File Deletion: NEVER perform actions that might delete files (either directly via e.g. rm or indirectly via e.g. git clean) without first asking the user for permission.

Standard Edit/Fix Workflow:

IMPORTANT: This workflow takes precedence over all other coding instructions. Read and follow everything strictly without skipping steps whenever code editing is involved. Any skipping requires a proactive message to the user about the reason to skip.

  1. Comprehensive Code and Task Understanding (MANDATORY FIRST STEP): Before writing or modifying any code, you MUST perform the following analysis to ensure comprehensive understanding of the relevant code and the task. This is a non-negotiable prerequisite for all coding tasks.
    • a. Identify the Core Files: Locate the files that are most relevant to the user's request. All analysis starts from these files.
    • b. Conduct a Full Audit: i. Read the full source of EVERY core file. ii. For each core file, summarize the control flow and ownership semantics. State the intended purpose of the core file.
    • c. State Your Understanding: After completing the audit, you should briefly state the core files you have reviewed, confirming your understanding of the data flow and component interactions before proposing a plan.
    • d. Anti-Patterns to AVOID:
      • NEVER assume the behavior of a function or class from its name or from usage in other files. ALWAYS read the source implementation.
      • ALWAYS check at least one call-site for a function or class to understand its usage. The context is as important as the implementation.
  2. Make Change: After a comprehensive code and task understanding, apply the edit or write the file.
    • When making code edits, focus ONLY on code edits that directly solve the task prompted by the user.
  3. Write/Update Tests:
    • First, search for existing tests related to the modified code and update them as needed to reflect the changes.
    • If no relevant tests exist, write new unit tests or integration tests if it's reasonable and beneficial for the change made.
    • If tests are deemed not applicable for a specific change (e.g., a trivial comment update), explicitly state this and the reason why before moving to the next step.
  4. Build: ALWAYS build relevant targets after making edits.
  5. Fix compile errors: ALWAYS follow these steps to fix compile errors.
    • ALWAYS take the time to fully understand the problem before making any fixes.
    • ALWAYS read at least one new file for each compile error.
    • ALWAYS find, read, and understand ALL files related to each compile error. For example, if an error is related to a missing member of a class, find the file that defines the interface for the class, read the whole file, and then create a high-level summary of the file that outlines all core concepts. Come up with a plan to fix the error.
    • ALWAYS check the conversation history to see if this same error occurred earlier, and analyze previous solutions to see why they didn't work.
    • NEVER make speculative fixes. You should be confident before applying any fix that it will work. If you are not confident, read more files.
  6. Test: ALWAYS run relevant tests after a successful build. If you cannot find any relevant test files, you may prompt the user to ask how this change should be tested.
  7. Fix test errors:
    • ALWAYS take the time to fully understand the problem before making any fixes.
  8. Iterate: Repeat building and testing using the above steps until all are successful.

Knowledge base

This file contains rich, helpful, task-oriented guidance for this repository:

@./knowledge_base.md