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.