mirror of
https://github.com/comfyanonymous/ComfyUI.git
synced 2026-04-15 13:02:35 +08:00
3fcffad8c4
Introduce repository guidance and reusable prompt templates. Adds AGENTS.md with repo-local environment, command, file-safety, git, validation, and ComfyUI-specific rules. Adds PROMPT_BUG_FIX.md, PROMPT_INSPECTION.md, PROMPT_NODE_REPAIR.md, and PROMPT_PACKAGE_INSTALL.md providing focused workflows for bug fixes, repository inspection, custom node repair, and package installation audits that enforce using the repo venv, PowerShell commands, minimal safe changes, and explicit validation/reporting.
115 lines
4.2 KiB
Markdown
115 lines
4.2 KiB
Markdown
# AGENTS.md
|
||
|
||
## Scope
|
||
|
||
These instructions apply to the entire repository unless a deeper AGENTS.md overrides them.
|
||
|
||
## Project context
|
||
|
||
This is a standard Git-based ComfyUI repository on Windows.
|
||
|
||
Repository root:
|
||
`C:\AI_PROJECTS\ComfyUI`
|
||
|
||
Primary Python environment:
|
||
`C:\AI_PROJECTS\ComfyUI\venv\Scripts\python.exe`
|
||
|
||
Primary shell:
|
||
Windows PowerShell
|
||
|
||
## Core working rules
|
||
|
||
- Preserve existing functionality unless the user explicitly asks for redesign or removal.
|
||
- Do not remove features, nodes, scripts, launchers, or config behavior unless explicitly told.
|
||
- Fix root causes instead of patching symptoms where practical.
|
||
- Reuse and improve existing logic instead of duplicating it.
|
||
- Do not invent files, APIs, packages, results, or test outcomes.
|
||
- Do not claim something was tested unless you actually ran the test or command.
|
||
- Keep changes tightly scoped to the user’s request.
|
||
- Stay focused on the current task. Do not perform unrelated cleanup or refactors.
|
||
- Prefer additive, reversible changes.
|
||
|
||
## Environment rules
|
||
|
||
- Always use the repo-local Python interpreter:
|
||
`C:\AI_PROJECTS\ComfyUI\venv\Scripts\python.exe`
|
||
- Never use a global Python, Conda environment, Windows Store Python, or some other interpreter unless the user explicitly asks.
|
||
- When installing packages, use:
|
||
`C:\AI_PROJECTS\ComfyUI\venv\Scripts\python.exe -m pip ...`
|
||
- Do not use bare `pip` commands.
|
||
- Assume the repo-local venv is the source of truth unless the user says otherwise.
|
||
|
||
## Command rules
|
||
|
||
When giving commands or running commands:
|
||
|
||
- Use Windows PowerShell syntax.
|
||
- Always state the working directory first.
|
||
- Prefer exact commands over summaries.
|
||
- Prefer commands that are safe to copy/paste.
|
||
|
||
## File safety rules
|
||
|
||
- Do not modify files outside this repository unless the user explicitly asks.
|
||
- Do not edit anything inside `venv\Lib\site-packages` unless the user explicitly asks for a local hotfix there.
|
||
- Do not delete models, outputs, checkpoints, LoRAs, embeddings, or user assets unless explicitly asked.
|
||
- Be careful with files under:
|
||
- `models\`
|
||
- `custom_nodes\`
|
||
- `user\`
|
||
- launch scripts
|
||
- config files
|
||
- Before changing behavior in `custom_nodes`, inspect that node’s current imports, dependencies, and startup assumptions.
|
||
|
||
## Git rules
|
||
|
||
If modifying files:
|
||
|
||
- Work on the current branch unless the user explicitly asks for a new one.
|
||
- Do not rewrite history.
|
||
- Do not amend existing commits unless the user explicitly asks.
|
||
- Do not create commits unless the user asks for a commit.
|
||
- Show `git status` after making changes when relevant.
|
||
|
||
## Validation rules
|
||
|
||
After code changes, run the smallest relevant validation that actually checks the change.
|
||
|
||
Preferred validation commands:
|
||
|
||
- Python syntax check for a file:
|
||
`C:\AI_PROJECTS\ComfyUI\venv\Scripts\python.exe -m py_compile <file>`
|
||
- Package import check:
|
||
`C:\AI_PROJECTS\ComfyUI\venv\Scripts\python.exe -c "import <module>; print('ok')"`
|
||
- If the change affects startup or node imports, use the repo-local environment and validate with the relevant launch command or targeted import path when practical.
|
||
- If a full startup test is too heavy, say so clearly and run the best targeted validation available.
|
||
|
||
## Reporting rules
|
||
|
||
In responses:
|
||
|
||
- State exactly which files were changed.
|
||
- State exactly which commands were run.
|
||
- State exactly what was verified and what was not verified.
|
||
- If something is risky, incomplete, or untested, say that plainly.
|
||
- Do not hide uncertainty.
|
||
|
||
## ComfyUI-specific guidance
|
||
|
||
- Treat startup logs as important evidence.
|
||
- When debugging node import failures, identify whether the problem is:
|
||
1. missing package
|
||
2. wrong package version
|
||
3. broken path/import
|
||
4. incompatible ComfyUI/custom-node API change
|
||
5. GPU/CUDA/Torch mismatch
|
||
- For package fixes, prefer minimal changes over large dependency churn.
|
||
- If a custom node shells out to `pip`, prefer replacing that with interpreter-safe commands using `python -m pip` when asked to fix it.
|
||
- Be cautious about torch, CUDA, TensorRT, xformers, flash-attn, triton, sageattention, and custom kernel packages because version mismatches can destabilize the whole stack.
|
||
|
||
## Instruction priority
|
||
|
||
- Follow direct user instructions first.
|
||
- Then follow deeper nested AGENTS.md files if present.
|
||
- Then follow this root AGENTS.md.
|