create-steering-documents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create Steering Documents

创建指导文档

Create comprehensive steering documents for a development project based on the project type and requirements.

为开发项目创建全面的指导文档，具体内容基于项目类型和需求而定。

Usage

使用方法

Create steering documents for [project description]

Create steering documents for [project description]

Examples

示例

Create steering documents for a React TypeScript e-commerce application

Create steering documents for a Python Django REST API with PostgreSQL

Create steering documents for a Node.js microservices architecture

Create steering documents for a Vue.js component library

Create steering documents for a React TypeScript e-commerce application

Create steering documents for a Python Django REST API with PostgreSQL

Create steering documents for a Node.js microservices architecture

Create steering documents for a Vue.js component library

What Are Steering Documents?

什么是指导文档？

Steering documents are contextual guidelines that influence how AI assistants approach development tasks. They contain project-specific standards, conventions, and best practices that help provide more relevant and consistent assistance.

指导文档是上下文相关的指南，用于指导AI助手处理开发任务的方式。它们包含项目特定的标准、约定和最佳实践，有助于提供更相关、更一致的协助。

How They Work

工作机制

Always Included (Default): Documents without front-matter are included in every interaction
File Match Conditional: Documents with
```
inclusion: fileMatch
```
are included when specific files are in context
Manual Inclusion: Documents with
```
inclusion: manual
```
are only included when explicitly referenced

始终包含（默认）：无前置元数据的文档会在每次交互中被包含
文件匹配条件：带有
```
inclusion: fileMatch
```
的文档会在上下文包含特定文件时被包含
手动包含：带有
```
inclusion: manual
```
的文档仅在被显式引用时才会被包含

Process

流程

1. Project Analysis

1. 项目分析

First, analyze the project requirements and determine which steering documents are needed:

For Frontend Projects (React, Vue, Angular):

Include: project-standards.md, git-workflow.md, frontend-standards.md, development-environment.md
Consider: component-library.md, testing-strategy.md

For Backend/API Projects (Node.js, Python, Java):

Include: project-standards.md, git-workflow.md, api-design.md, development-environment.md
Consider: database-standards.md, security-guidelines.md

For Full-Stack Projects:

Include: All core documents plus technology-specific ones
Consider: deployment-standards.md, monitoring-guidelines.md

For Library/Package Projects:

Include: project-standards.md, git-workflow.md, documentation-standards.md
Consider: versioning-strategy.md, publishing-guidelines.md

首先，分析项目需求并确定所需的指导文档：

前端项目（React、Vue、Angular）：

必选：project-standards.md、git-workflow.md、frontend-standards.md、development-environment.md
可选：component-library.md、testing-strategy.md

后端/API项目（Node.js、Python、Java）：

必选：project-standards.md、git-workflow.md、api-design.md、development-environment.md
可选：database-standards.md、security-guidelines.md

全栈项目：

必选：所有核心文档加上技术特定文档
可选：deployment-standards.md、monitoring-guidelines.md

库/包项目：

必选：project-standards.md、git-workflow.md、documentation-standards.md
可选：versioning-strategy.md、publishing-guidelines.md

2. Core Document Templates

2. 核心文档模板

project-standards.md

markdown

undefined

markdown

undefined

Project Standards and Guidelines

Code Quality Standards

Follow language-specific style guides (ESLint for JS/TS, Black for Python, etc.)
Maintain consistent naming conventions across the codebase
Write self-documenting code with clear variable and function names
Include meaningful comments for complex business logic
Keep functions small and focused on single responsibilities

Follow language-specific style guides (ESLint for JS/TS, Black for Python, etc.)
Maintain consistent naming conventions across the codebase
Write self-documenting code with clear variable and function names
Include meaningful comments for complex business logic
Keep functions small and focused on single responsibilities

Testing Requirements

Write unit tests for all business logic functions
Maintain minimum 80% code coverage
Include integration tests for API endpoints
Write end-to-end tests for critical user flows
Use descriptive test names that explain the scenario being tested

Write unit tests for all business logic functions
Maintain minimum 80% code coverage
Include integration tests for API endpoints
Write end-to-end tests for critical user flows
Use descriptive test names that explain the scenario being tested

Documentation Standards

Update README.md for any significant changes
Document API endpoints with clear examples
Include setup and deployment instructions
Maintain changelog for version releases
Document architectural decisions in ADR format

Update README.md for any significant changes
Document API endpoints with clear examples
Include setup and deployment instructions
Maintain changelog for version releases
Document architectural decisions in ADR format

Security Practices

Never commit secrets, API keys, or passwords
Use environment variables for configuration
Validate all user inputs
Implement proper authentication and authorization
Follow OWASP security guidelines

Never commit secrets, API keys, or passwords
Use environment variables for configuration
Validate all user inputs
Implement proper authentication and authorization
Follow OWASP security guidelines

Performance Guidelines

Optimize database queries and avoid N+1 problems
Implement caching where appropriate
Use lazy loading for large datasets
Monitor and profile performance regularly
Consider scalability in architectural decisions

undefined

Optimize database queries and avoid N+1 problems
Implement caching where appropriate
Use lazy loading for large datasets
Monitor and profile performance regularly
Consider scalability in architectural decisions

undefined

git-workflow.md

markdown

undefined

markdown

undefined

Git Workflow and Branching Strategy

Branch Naming Convention

Feature branches:
```
feature/description-of-feature
```
Bug fixes:
```
fix/description-of-bug
```
Hotfixes:
```
hotfix/critical-issue-description
```
Releases:
```
release/version-number
```

Feature branches:
```
feature/description-of-feature
```
Bug fixes:
```
fix/description-of-bug
```
Hotfixes:
```
hotfix/critical-issue-description
```
Releases:
```
release/version-number
```

Commit Message Format

Follow conventional commits format:

type(scope): description

[optional body]

[optional footer]

Types: feat, fix, docs, style, refactor, test, chore

Follow conventional commits format:

type(scope): description

[optional body]

[optional footer]

Types: feat, fix, docs, style, refactor, test, chore

Pull Request Guidelines

Create PR from feature branch to main/develop
Include clear description of changes
Link related issues using keywords (fixes #123)
Ensure all tests pass before requesting review
Squash commits when merging to keep history clean

Create PR from feature branch to main/develop
Include clear description of changes
Link related issues using keywords (fixes #123)
Ensure all tests pass before requesting review
Squash commits when merging to keep history clean

Code Review Process

At least one approval required before merge
Review for code quality, security, and performance
Check that tests cover new functionality
Verify documentation is updated if needed
Ensure no breaking changes without proper versioning

undefined

At least one approval required before merge
Review for code quality, security, and performance
Check that tests cover new functionality
Verify documentation is updated if needed
Ensure no breaking changes without proper versioning

undefined

frontend-standards.md

markdown

---
inclusion: fileMatch
fileMatchPattern: '*.tsx|*.jsx|*.vue|*.svelte'
---

markdown

---
inclusion: fileMatch
fileMatchPattern: '*.tsx|*.jsx|*.vue|*.svelte'
---

Frontend Development Standards

Component Architecture

Use functional components with hooks (React)
Keep components small and focused
Implement proper prop validation
Use TypeScript for type safety
Follow component composition patterns

Use functional components with hooks (React)
Keep components small and focused
Implement proper prop validation
Use TypeScript for type safety
Follow component composition patterns

State Management

Use local state for component-specific data
Implement global state for shared application data
Use proper state management libraries (Redux, Zustand, Pinia)
Avoid prop drilling with context or state management

Use local state for component-specific data
Implement global state for shared application data
Use proper state management libraries (Redux, Zustand, Pinia)
Avoid prop drilling with context or state management

Styling Guidelines

Use CSS modules or styled-components for component styling
Follow BEM methodology for CSS class naming
Implement responsive design with mobile-first approach
Use CSS custom properties for theming
Maintain consistent spacing and typography scales

Use CSS modules or styled-components for component styling
Follow BEM methodology for CSS class naming
Implement responsive design with mobile-first approach
Use CSS custom properties for theming
Maintain consistent spacing and typography scales

Performance Optimization

Implement code splitting and lazy loading
Use React.memo or similar for expensive components
Optimize images and assets
Implement proper caching strategies
Monitor bundle size and performance metrics

Implement code splitting and lazy loading
Use React.memo or similar for expensive components
Optimize images and assets
Implement proper caching strategies
Monitor bundle size and performance metrics

Accessibility Standards

Use semantic HTML elements
Implement proper ARIA attributes
Ensure keyboard navigation support
Maintain proper color contrast ratios
Test with screen readers

undefined

Use semantic HTML elements
Implement proper ARIA attributes
Ensure keyboard navigation support
Maintain proper color contrast ratios
Test with screen readers

undefined

api-design.md

markdown

---
inclusion: manual
---

markdown

---
inclusion: manual
---

API Design Guidelines

RESTful API Standards

Use HTTP methods appropriately (GET, POST, PUT, DELETE, PATCH)
Follow resource-based URL patterns:
```
/api/v1/users/{id}
```
Use plural nouns for resource collections
Implement proper HTTP status codes
Include API versioning in URL path

Use HTTP methods appropriately (GET, POST, PUT, DELETE, PATCH)
Follow resource-based URL patterns:
```
/api/v1/users/{id}
```
Use plural nouns for resource collections
Implement proper HTTP status codes
Include API versioning in URL path

Request/Response Format

Use JSON for request and response bodies
Follow consistent naming conventions (camelCase or snake_case)
Include pagination for list endpoints
Implement proper error response format:

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input provided",
    "details": ["Email is required", "Password too short"]
  }
}

Use JSON for request and response bodies
Follow consistent naming conventions (camelCase or snake_case)
Include pagination for list endpoints
Implement proper error response format:

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input provided",
    "details": ["Email is required", "Password too short"]
  }
}

Authentication and Authorization

Use JWT tokens for stateless authentication
Implement proper token refresh mechanisms
Use role-based access control (RBAC)
Rate limit API endpoints to prevent abuse

Use JWT tokens for stateless authentication
Implement proper token refresh mechanisms
Use role-based access control (RBAC)
Rate limit API endpoints to prevent abuse

Documentation

Use OpenAPI/Swagger for API documentation
Include request/response examples
Document all possible error responses
Provide SDK or client library examples

undefined

Use OpenAPI/Swagger for API documentation
Include request/response examples
Document all possible error responses
Provide SDK or client library examples

undefined

development-environment.md

markdown

---
inclusion: fileMatch
fileMatchPattern: 'package.json|requirements.txt|Dockerfile|docker-compose.yml'
---

markdown

---
inclusion: fileMatch
fileMatchPattern: 'package.json|requirements.txt|Dockerfile|docker-compose.yml'
---

Development Environment Setup

Local Development

Use Node.js version specified in .nvmrc file
Install dependencies with
```
npm ci
```
for consistent builds
Use Docker for local database and service dependencies
Run linting and formatting before committing changes

Use Node.js version specified in .nvmrc file
Install dependencies with
```
npm ci
```
for consistent builds
Use Docker for local database and service dependencies
Run linting and formatting before committing changes

Environment Variables

Copy
```
.env.example
```
to
```
.env
```
for local development
Never commit actual environment files
Document all required environment variables in README
Use different prefixes for different environments (DEV_, PROD_, etc.)

Copy
```
.env.example
```
to
```
.env
```
for local development
Never commit actual environment files
Document all required environment variables in README
Use different prefixes for different environments (DEV_, PROD_, etc.)

Database Management

Use migrations for all schema changes
Include rollback scripts for migrations
Seed data should be idempotent
Backup database before major changes

Use migrations for all schema changes
Include rollback scripts for migrations
Seed data should be idempotent
Backup database before major changes

Build and Deployment

Ensure builds are reproducible across environments
Use multi-stage Docker builds for optimization
Include health checks in containerized applications
Document deployment procedures and rollback steps

Ensure builds are reproducible across environments
Use multi-stage Docker builds for optimization
Include health checks in containerized applications
Document deployment procedures and rollback steps

Debugging and Logging

Use structured logging with appropriate log levels
Include correlation IDs for request tracing
Set up proper error monitoring and alerting
Use debugger instead of console.log for development

undefined

Use structured logging with appropriate log levels
Include correlation IDs for request tracing
Set up proper error monitoring and alerting
Use debugger instead of console.log for development

undefined

3. Content Customization

3. 内容定制

Language/Framework Specific Adaptations:

JavaScript/TypeScript: ESLint, Prettier, Jest, package.json scripts
Python: Black, flake8, pytest, requirements.txt, virtual environments
Java: Checkstyle, Maven/Gradle, JUnit, Spring Boot conventions
Go: gofmt, go mod, testing patterns, project structure
Rust: rustfmt, Cargo.toml, cargo test, clippy

Project Scale Adaptations:

Small Projects: Lightweight processes, minimal tooling
Team Projects: Code review requirements, shared standards
Enterprise: Comprehensive security, compliance, documentation

Domain Specific Considerations:

E-commerce: PCI compliance, performance, security
Healthcare: HIPAA compliance, data privacy, audit trails
Finance: Security standards, regulatory compliance
Open Source: Contribution guidelines, licensing, community standards

语言/框架特定适配：

JavaScript/TypeScript：ESLint、Prettier、Jest、package.json脚本
Python：Black、flake8、pytest、requirements.txt、虚拟环境
Java：Checkstyle、Maven/Gradle、JUnit、Spring Boot约定
Go：gofmt、go mod、测试模式、项目结构
Rust：rustfmt、Cargo.toml、cargo test、clippy

项目规模适配：

小型项目：轻量化流程、最少工具
团队项目：代码审查要求、共享标准
企业级项目：全面的安全、合规、文档

领域特定考虑：

电商：PCI合规、性能、安全
医疗：HIPAA合规、数据隐私、审计跟踪
金融：安全标准、监管合规
开源：贡献指南、许可证、社区标准

4. File Reference Integration

4. 文件引用集成

Include relevant external files using the

#[[file:path]]

syntax:

OpenAPI specifications for API projects
Database schemas for backend projects
Design system tokens for frontend projects
Configuration files for environment setup

使用

#[[file:path]]

语法包含相关外部文件：

API项目的OpenAPI规范
后端项目的数据库 schema
前端项目的设计系统令牌
环境设置的配置文件

5. Quality Checklist

5. 质量检查清单

Output Structure

输出结构

Create steering documents in the

.kiro/steering/

directory:

.kiro/steering/
├── project-standards.md      (always included)
├── git-workflow.md           (always included)
├── frontend-standards.md     (fileMatch: *.tsx,*.jsx)
├── api-design.md             (manual inclusion)
└── development-environment.md (fileMatch: package.json)

在

.kiro/steering/

目录中创建指导文档：

.kiro/steering/
├── project-standards.md      (always included)
├── git-workflow.md           (always included)
├── frontend-standards.md     (fileMatch: *.tsx,*.jsx)
├── api-design.md             (manual inclusion)
└── development-environment.md (fileMatch: package.json)

Front-matter Options

前置元数据选项

yaml

---
inclusion: always|fileMatch|manual
fileMatchPattern: 'glob-pattern'  # for fileMatch only
---

yaml

---
inclusion: always|fileMatch|manual
fileMatchPattern: 'glob-pattern'  # for fileMatch only
---

Best Practices

最佳实践

Do:

建议：

Keep documents focused and specific
Use clear, actionable language
Include concrete examples
Reference external specifications
Update regularly as project evolves
Use appropriate inclusion mechanisms

保持文档聚焦且具体
使用清晰、可操作的语言
提供具体示例
引用外部规范
随着项目发展定期更新
使用合适的包含机制

Don't:

避免：

Create overly broad or generic guidelines
Duplicate information across multiple documents
Include sensitive information or secrets
Create conflicting standards
Make documents too long or complex

创建过于宽泛或通用的指南
在多个文档中重复信息
包含敏感信息或机密
创建冲突的标准
使文档过长或过于复杂