Agentic Coding Instructions

python.md

General Coding Instructions

1. Response Structure & Workflow

• Every response must follow this specific sequence:
  • File Hierarchy: Provide a visual tree of the file structure and a one-line description for each file involved.
  • Class & Inheritance (if applicable): Briefly explain the inheritance structure and how files relate to one another.
  • The Code Implementation: (See "Code Formatting" for style rules).
  • Summary of Changes: A concise list of what was modified or added.
  • Execution Commands: Provide the specific PowerShell command to run the script and a JSON code block for the VSCode launch.json configuration.
  • Agent Learnings: A section titled "Learnings & Improvements" summarizing logic hurdles or prompt refinements for future sessions.

2. Code Logic & Step Numbering

• Step-wise Logic: Break down logic into numbered steps (e.g., # Step 1: Initialize...).
  • Step 0: Reserve "Step 0" for initializations (logging, auth checks, configuration loading).
• Function Scope: Step numbers are local to each function. Do not increment the counter across the entire file.
• Import Rule: Imports are never treated as a step.

3. Naming Conventions & Configuration

• camelCase: Use camelCase for all variable, function and file names (especially the ones the agent generates)..
• UPPER_CASE: Use UPPER_CASE_WITH_UNDERSCORES for constants and variables in config.py.
• No Hardcoding: Never hardcode environment variables, file paths, or dictionary keys.
  • Use a config.py file or a .env file for these.
  • In the main code, refer to these as config.VARIABLE_NAME.
  • For single-file scripts, define these constants at the very top of the file.
• Do not make markdown files unless specifically asked for.
• • For imports, always use the full relative path from the extension root. For e.g., assume the following folder structure:

    <root>/
      utils/
        config.py
        someLogic.py // (note that this file is in camelCase)
      main.py
    

    • In main.py do ``` import utils.config as config import utils.someLogic as someLogic

       tmp = config.VARIABLE_NAME
       someLogic.someFunction(tmp)
       ```
      

4. Visual Organization & Readability

• Section Banners: Separate major code sections (e.g., Globals, Classes, Main Logic) with: ###################################################################### #
  ######################################################################
• Function Banners: Group related functions using type banners: # ======= HELPER FUNCTIONS ======== # ======= LOGIC FUNCTIONS ========
• Clean Comments: Use standard # for logic comments. Use the banners above only for structural separation.
• Custom vs Overridden: When overriding library classes, add comments to distinguish between inherited methods and your custom logic.

Python Best Practices

• Imports: Organize into three distinct sections:

• General/Standard library imports.

• Pip/Third-party installs (add a # pip install comment next to new libraries).

• Application/Local module imports.

• File Paths: Always use the pathlib library for path manipulation.

• CLI Arguments: Use argparse for any script that requires inputs (folder paths, IDs, etc.).

• Logging: Use clear print separators in logs (e.g., print("----- Step 1: Description -----")).

• Progress Tracking: Use tqdm for loops, especially when processing folders or large datasets.

• No New Envs: Do not suggest creating new conda/venv environments during the session; simply note the required installs.

• VSCode Integration: Always output content for launch.json inside a code block; do not create separate .json or .md files unless explicitly requested.

• Duplicate Check: Before finalizing code, ensure no functions or comments are duplicated across the sequence of calls.

reasoning.md

General Reasoning Approach

1. Think before coding Don't assume. Don't hide confusion. State ambiguity explicitly. Present multiple interpretations rather than silently picking one. Push back if a simpler approach exists. Stop and ask rather than guess.

2. Simplicity first No features beyond what was asked. No abstractions for single-use code. No "flexibility" that wasn't requested. No error handling for impossible scenarios. The test: would a senior engineer say this is overcomplicated? If yes, rewrite it.

3. Surgical changes Don't "improve" adjacent code. Don't refactor things that aren't broken. Match the existing style even if you'd do it differently. If you notice unrelated dead code, mention it, don't delete it. Every changed line should trace directly to the request.

4. Goal-driven execution Transform "fix the bug" into "write a test that reproduces it, then make it pass." Transform "add validation" into "write tests for invalid inputs, then make them pass." Give it success criteria and watch it loop until done.