القائمة
编写优化 Agents.md 时需要遵循的规范、风格、指南
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Pre-scan Markdown files before reading. Use `sspec tool mdtoc` to get file size + heading structure with line numbers (L<n> format) before reading long docs, SKILLs, or spec-docs. Eliminates blind reads.
Assess scale, create change, fill spec.md + design.md, align with user. Use after clarify when ready to define the solution.
Execute tasks from tasks.md. Implement code changes, update progress. Use after plan approval.
Break design into concrete tasks. Fill tasks.md with file-level execution plan. Use after design alignment.
User acceptance and feedback loop. Handle argue-improve cycles until user is satisfied.
Build shared understanding through dialogue and investigation. Produces Problem Statement + direction sketch. Reusable posture, not rigid phase.
| name | write-agents |
| description | 编写优化 Agents.md 时需要遵循的规范、风格、指南 |
When improving the AGENTS.md template or writing AI guidance documents, apply these principles:
Definition: Every paragraph MUST translate to concrete Agent actions or decision criteria.
Litmus test: For each paragraph, ask— "After reading this, what does the Agent do next?" If the answer is vague, the paragraph is ineffective.
| Pattern | ❌ Ineffective (Will Be Ignored) | ✅ Effective (Actionable) |
|---|---|---|
| Tech stack listing | Tech stack: React 18, TypeScript, Tailwind | Components MUST use React function components + TypeScript. Styling MUST use Tailwind classes; CSS files are FORBIDDEN. |
| Important markers | Important file: src/config/settings.ts | When adding environment variables, MUST update default values in src/config/settings.ts |
| Vague quality asks | Keep code clean | Functions >40 lines MUST be split. Files >300 lines SHOULD be split into modules. |
| Implicit expectations | Follow existing project style | Naming: Components=PascalCase, hooks=camelCase with "use" prefix, constants=UPPER_SNAKE_CASE |
| Abstract goals | Consider performance and security | Database queries MUST use parameterized statements. Lists >50 items MUST use virtual scrolling. |
| Background info | This is an e-commerce backend service | This service handles payments. Monetary calculations MUST use Decimal; float is FORBIDDEN. |
Definition: Never assume the Agent will "understand intent" or "automatically connect context." All expected behaviors must be stated explicitly.
Anti-pattern:
❌ IMPLICIT EXPECTATION
## Project Structure
src/
├── components/ # Reusable components
├── features/ # Business modules
└── utils/ # Utilities
(User's thought: Agent should know where to put new code, right?)
(Reality: Agent may place files randomly or ask every time)
Correct pattern:
✅ EXPLICIT RULES
## File Placement Rules
When creating new files, determine location by type:
| File Type | Target Path | Example |
|-----------|-------------|---------|
| Feature-specific component | src/features/{feature}/components/ | src/features/checkout/components/ |
| Global utility | src/utils/ | src/utils/format.ts |
Definition: Provide exactly what the Agent needs to complete the task—no more, no less.
Anti-pattern: Including a 500-line API reference when Agent only needs 3 endpoints Correct: Reference the doc, specify which endpoints to use, state the constraints
Definition: Same input → predictable output. Eliminate ambiguity.
Anti-pattern: "You can use A, B, or C" → Agent may choose differently each time
Correct patterns:
✅ Priority order: Try A first. If A fails, use B. C is last resort.
✅ Selection criteria:
- Use A when: <condition>
- Use B when: <condition>
- Default to C otherwise