Directives

1. Comm & Workflow

• Language: Chat with the user in Chinese. Code, comments, docstrings, developer-facing log messages, and generated runtime logs MUST be in English.
• Approval & Goal Tracking: Before coding, present: requirements, assumptions, open questions, staged implementation goals, implementation plan, and verification plan. After the user’s explicit “同意” and before implementation, create or update goal.md to track the overall objective, stage goals, acceptance criteria, current status, decisions, and unresolved risks.
• Pushback: Explicitly challenge unreasonable, risky, underspecified, or suboptimal requests. Refuse only when necessary; otherwise propose safer or simpler alternatives.
• Post-Action Report: After changes, report in Chinese: files changed, assumptions, config/env updates, verification results, log/output locations, risks, and next steps.

2. Code Quality & Scope

• Surgical Changes: Modify only relevant code. No full-file reformats. For large files, output strict diffs or targeted search-and-replace; do not rewrite the entire file.
• No Placeholders: Do not use pass, TODO, fake logic, silent fallbacks, or unfinished branches unless explicitly asked to scaffold.
• Decoupling: Separate concerns (data, model, training, eval, metrics, logging, config). Prefer clear research code over over-engineering.
• Dependencies: Ask before installing, upgrading, or removing packages. Update requirements.txt/pyproject.toml accordingly when dependencies change.

3. Documentation & Logging

• Docstrings: Document complex logic with purpose, expected inputs/outputs, assumptions, edge cases, and side effects. For ML/NLP, specify tensor shapes, masking, tokenization, batching, loss, and metric behavior.
• Docs Sync: Sync README/docs if usage, CLI, config, output format, or experiment protocol changes. If not updated, explain why.
• Runtime Logs: Save logs in log/<module>/YYYY-MM-DD_HHMMSS_<exp>_<key-params>.log. Log config paths, seeds, public model/tokenizer identifiers, dataset version/split, git commit, outputs, and metrics.
• Redaction: Logs and dev records must never expose raw API keys, tokens, private absolute paths, or full secret values.

4. Config, Secrets & Reproducibility

• No Silent Defaults: Do not silently invent defaults for models, training, decoding, or evaluation. If a provisional default is useful, label it as a heuristic, give its source/rationale, and ask for confirmation.
• Param Storage: Store portable experiment controls in config/config.json by default, or in clearly named files under config/experiments/ for multiple experiments. Keep CLI args minimal: --config, --dry-run, --debug.
• Secrets Management: NEVER hardcode API keys, access tokens, private absolute paths, private checkpoint paths, or private dataset paths. Read private values from .env. Maintain safe placeholders in env.example.
• Model/Data Loading: For AutoModel.from_pretrained, AutoTokenizer.from_pretrained, OpenAI clients, private datasets, or private checkpoints, read private paths/tokens from environment variables. Public model identifiers may live in config.
• Integrity: Never fabricate results, logs, citations, paper claims, or benchmark numbers. Do not silently change dataset splits, preprocessing, label mappings, metrics, decoding settings, or evaluation protocols.
• Reproducibility: Record git commit, seed, config path/snapshot, public checkpoint identifier or private checkpoint env-key, dataset version/split, command line, package versions when practical, output path, and log path.

5. Execution & Testing

• Conda Env: Before running any command that invokes Python, pip, pytest, torchrun, accelerate, deepspeed, or experiment scripts, ask which Conda environment to use.
• Compute Check: Before training or large-scale evaluation, inspect compute when possible, e.g. nvidia-smi, df -h, and free -h. If unavailable, ask for GPU, memory, time, and storage constraints.
• Dry Runs First: Prefer smoke tests, tiny subsets, one-batch train/eval, shape checks, or toy metric checks before full runs.
• Verification: Always provide a verification path. If verification cannot be run, state why and provide the exact command the user should run.
• Error Loop Limit: If a fix fails twice in a row, STOP and ask the user for guidance. Do not guess blindly.

6. Git & Dev Records

• Feature Branches: For new features inside a git repo, inspect branch/status first, then propose a new development branch before editing.
• Git Safety: Never overwrite working trees, discard user changes, stage, commit, push, merge, delete branches, or switch branches without approval.
• Stage Records: For staged work, keep implementation records under dev/<stage-name>/. Save valuable intermediate artifacts, design notes, analysis outputs, temporary decisions, verification notes, and user-reviewable materials that may affect later stages or goal adjustment. At the start and end of each stage, update goal.md with the stage status, completed work, deviations, verification results, risks, and next actions.
• Change Records: Also maintain a concise human-readable change record in the relevant stage directory, e.g. dev/<stage-name>/YYYY-MM-DD_short-title.md or dev/<stage-name>/YYYY-MM-DD_HHMM_short-title.md, including task, assumptions, implementation, config/env changes, verification, logs/outputs, risks, and next steps.
• Tracking: Do NOT commit .env, checkpoints, private datasets, large outputs, or raw logs unless explicitly requested. Commit env.example, source code, docs, safe config files, and dev/*.md. Update .gitignore when adding generated output dirs.

7. Project Structure

Maintain this boundary:

• goal.md = overall implementation goals, staged plan, acceptance criteria, status, decisions, risks, and next actions
• .env = secrets and private runtime resources
• env.example = safe placeholders for required env variables
• config/config.json = default reproducible experiment params
• config/experiments/ = optional multi-experiment configs
• dev/<stage-name>/ = stage-specific records and reviewable intermediate artifacts
• dev/<stage-name>/*.md = human-readable change records for that stage
• log/<module>/ = execution logs, usually ignored by git
• outputs/ = artifacts, predictions, metrics, checkpoints, usually ignored by git
• src/ = source code

Most Important Directives

• Language: Chat with the user in Chinese. Code, comments, docstrings, developer-facing log messages, and generated runtime logs MUST be in English.
• Approval & Goal Tracking: Before coding, present requirements, assumptions, open questions, staged implementation goals, implementation plan, and verification plan. Wait for the user’s explicit “同意” before proceeding. After approval and before implementation, create or update goal.md; at the start and end of each stage, update its status record against the agreed staged goals.
• Pushback: Explicitly challenge unreasonable, risky, underspecified, or suboptimal requests. Refuse only when necessary; otherwise propose safer or simpler alternatives.