How to Use the Pitfalls Guide in GPT-Image-2 Templates: A Complete Developer Reference

The Pitfalls Guide (避坑指南) embedded throughout docs/templates.md provides explicit "avoid-pitfall" constraints that you append directly to your prompt or JSON payload, giving the model concrete guardrails that eliminate ambiguous outputs and enforce strict visual fidelity.

The pitfalls guide in GPT-Image-2 templates serves as a critical safety net within the freestylefly/awesome-gpt-image-2 repository. Each template in the master catalog terminates with a curated list of common failure modes—ranging from vague platform specifications to unreadable text—paired with imperative constraints that prevent the model from generating low-quality or inconsistent visuals. By integrating these guardrails into your generation workflow, you transform natural language descriptions into machine-readable directives that dramatically improve output reliability.

Where the Pitfalls Guide Lives in the Repository

The master template file [docs/templates.md](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md) houses the complete Pitfalls Guide. Every template section in this file concludes with a dedicated 避坑指南 subsection containing bullet-pointed constraints. This proximity ensures that the safeguards remain synchronized with their corresponding base prompts, allowing you to copy-paste the entire block—template plus pitfalls—without hunting through separate documentation.

Anatomy of the Pitfalls Guide

The guide operates through three distinct mechanisms that convert human intent into model constraints.

Contextual Safety Net

Each pitfalls section enumerates the most frequent failure modes for a specific visual style. For example, UI screenshot templates warn against mixing platform features (such as combining Twitter’s blue verification checkmark with TikTok’s music disc animation), while infographic templates guard against information hierarchy collapse.

Explicit Constraint Syntax

Every bullet point utilizes strong imperative phrasing—typically starting with 不要… (Do not…) or 强制… (Mandatory…)—to create unambiguous machine-readable instructions. When you copy these clauses into your prompt, they function as negative constraints that override the model’s tendency to hallucinate generic or conflicting visual elements.

Template-Level Integration

The pitfalls live immediately adjacent to the base template (whether plain-text or JSON). This structural decision, implemented in [docs/templates.md](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md), guarantees that every template modification automatically carries its corresponding safety constraints, preventing version drift between the prompt logic and its guardrails.

Step-by-Step Workflow for Using the Pitfalls Guide

Follow this four-step process to leverage the guide in your image generation pipeline:

1. Select a template from the visual category you need (UI screenshot, infographic, poster, etc.) in [docs/templates.md](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md).
2. Copy the base prompt—either the plain-text description or the JSON schema—for your chosen style.
3. Append the "avoid-pitfall" bullet list from the 避坑指南 section directly beneath your primary prompt content.
4. Submit the combined payload to the /api/generate-image endpoint or invoke the skill’s generate function to produce the final image.

Code Implementation Examples

Plain-Text Prompt with Pitfalls

When submitting natural language prompts, append the pitfalls section as a markdown list at the end of your text block:

为[产品类型]生成一张[平台，如 iOS/Android/Web]界面图。
核心功能：[功能点A]、[功能点B]、[功能点C]。
视觉风格：[极简/科技/拟物]，主色[颜色]，强调色[颜色]。
布局：[顶部导航/双栏/卡片流]，信息层级清晰，留白充足。
输出：高保真UI截图，文字清晰可读，比例[9:16/16:9]。

# 避坑指南

- **不要给模糊指令**：明确 "平台 + 比例 + 布局"，否则模型会像个实习生一样乱排版。
- **强制文字锁定**：要求 "文字绝对可读，必须显示指定的中文"，避免出现乱码按钮和毫无意义的火星文。
- **截图区分平台特征**：X（Twitter）有蓝勾认证、转发/引用区分；抖音有音乐碟片和点赞动画；小红书有双列瀑布流特征。生成前指定平台，否则模型会混搭。

The two “avoid-pitfall” items provide strict directives that resolve the most common ambiguities for UI generation, specifically targeting platform fidelity and text legibility.

JSON Payload with avoid_pitfalls Array

For programmatic interfaces, structure the constraints within a dedicated array that the skill layer merges into the final prompt:

{
  "type": "UI Screenshot",
  "platform": "iOS",
  "product": "Fitness App",
  "layout": "Card-based feed with bottom tab bar",
  "style": {
    "theme": "Dark Mode",
    "primary_color": "Neon Green",
    "typography": "Clean sans-serif"
  },
  "content": {
    "header": "Today's Activity",
    "cards": [
      {"title": "Running", "data": "5.2 km", "button": "Start"},
      {"title": "Calories", "data": "340 kcal"}
    ]
  },
  "constraints": "High fidelity, readable text, 9:16 aspect ratio",
  "avoid_pitfalls": [
    "不要给模糊指令：明确平台、比例和布局",
    "强制文字锁定：文字必须可读且显示指定的中文"
  ]
}

Pass this JSON to the generate function defined in [agents/skills/gpt-image-2-style-library/SKILL.md](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/agents/skills/gpt-image-2-style-library/SKILL.md). The skill internally concatenates the avoid_pitfalls array into the prompt string before forwarding the request to the image generation API.

Programmatic Integration in Node.js

When building agents that consume the style library, use the generateImage helper to automatically merge templates with their pitfalls:

import { generateImage } from '@gpt-image-2/style-library';

// Build a UI prompt with pitfalls
const prompt = {
  type: 'UI Screenshot',
  platform: 'Web',
  product: 'Project Management Tool',
  layout: 'Two‑column dashboard',
  style: { theme: 'Minimal', primary_color: '#0066FF' },
  constraints: 'High fidelity, readable text, 16:9 aspect ratio',
  avoid_pitfalls: [
    '不要给模糊指令：明确平台、比例和布局',
    '强制文字锁定：文字必须可读且显示指定的中文'
  ]
};

generateImage(prompt)
  .then(url => console.log('Generated image URL:', url))
  .catch(err => console.error('Generation failed:', err));

The generateImage utility guarantees that every request respects the safety constraints by prepending the avoid_pitfalls content to the generation context before calling the back-end endpoint.

Critical Source Files for Developers

Understanding the repository architecture helps you locate and extend the pitfalls logic:

• [docs/templates.md](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md) — Master catalog of all industrial-level prompt templates and their accompanying Pitfalls Guide sections.
• [agents/skills/gpt-image-2-style-library/SKILL.md](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/agents/skills/gpt-image-2-style-library/SKILL.md) — Defines the skill-level interface, including the generate function that merges avoid_pitfalls arrays into final prompt strings.
• [agents/skills/gpt-image-2-style-library/references/style-library.md](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/agents/skills/gpt-image-2-style-library/references/style-library.md) — Developer reference for prompt construction, JSON formatting, and embedding avoid-pitfall clauses.
• [api/generate-image.js](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js) — Back-end endpoint that receives the finalized prompt (text or JSON) and forwards it to the underlying image model.
• [data/style-library.json](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json) — JSON catalog of all templates for programmatic lookup of template IDs and their associated pitfalls.

Summary

• The Pitfalls Guide (避坑指南) lives in [docs/templates.md](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md) as a curated list of negative constraints appended to each template.
• Explicit imperatives ("不要…", "强制…") prevent the model from generating ambiguous platform features, unreadable text, or mixed visual styles.
• You can inject pitfalls via plain-text markdown lists appended to prompts or through the avoid_pitfalls JSON array consumed by the skill’s generate function.
• The agents/skills/gpt-image-2-style-library/ module handles automatic merging of pitfalls with base templates before API submission.
• Using the guide transforms vague natural-language instructions into machine-readable guardrails, significantly improving the reliability and visual fidelity of GPT-Image-2 outputs.

Frequently Asked Questions

What is the Pitfalls Guide in GPT-Image-2 templates?

The Pitfalls Guide is a set of negative constraints (labeled 避坑指南 in the source) documented in [docs/templates.md](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md). It lists specific mistakes to avoid—such as mixing iOS and Android UI elements or generating illegible text—providing imperative commands that override the model’s default behavior and enforce strict adherence to the intended visual style.

How do I add pitfalls to a JSON prompt payload?

Include an avoid_pitfalls array as a top-level key in your JSON object, populated with string values copied from the 避坑指南 section of your chosen template. When you pass this payload to the generate function in [SKILL.md](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/agents/skills/gpt-image-2-style-library/SKILL.md), the skill automatically concatenates these constraints into the final prompt sent to the image generation API.

Where are the pitfalls definitions stored?

All pitfalls definitions reside in [docs/templates.md](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md) at the repository root. Each template section concludes with its specific 避坑指南 subsection. Additionally, structured metadata for programmatic access exists in [data/style-library.json](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json), which catalogs template IDs and their associated constraint sets.

Can I customize the pitfalls for my own templates?

Yes. The repository structure allows you to append custom 避坑指南 sections to any new template you create in [docs/templates.md](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md). Ensure your custom pitfalls follow the imperative syntax ("不要…" for prohibitions, "强制…" for requirements) so that the agents/skills/gpt-image-2-style-library/ skill layer can parse and merge them correctly during generation workflows.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}