AI Coding Best Practices

AI Coding Best Practices

Introduction

After a year of AI coding practice, HotelByte project has evolved from initial “copy-paste coding” to a complete AI-assisted development system. This article will summarize our best practices, including efficiency improvement data, code quality standards, forward-thinking design innovation, and future planning.

Efficiency Improvement Data

Development Efficiency Comparison

Metric Traditional Development DeepSeek Era Claude Code + OpenSpec Improvement
Feature development time 5-7 days 3-5 days 1-2 days 3.5x
Bug fix time 2-4 hours 1-2 hours 30-60 minutes 3x
Code review time 1-2 hours 1-1.5 hours 30-45 minutes 2x
Test writing time 2-3 hours 1.5-2 hours 30-60 minutes 3x
Documentation time 1-2 hours 1-1.5 hours 5-10 minutes 10x

Cost Analysis

Cost Type Traditional Development AI Coding Savings
Development labor cost $10,000/month $5,000/month 50%
AI tool cost $0 $300/month -$300
Training cost $2,000 $1,000 50%
Bug fix cost $3,000/month $500/month 83%
Total Cost $15,000/month $6,800/month 55%

Quality Metrics

Metric Traditional Development AI Coding Improvement
Test coverage 40-50% 65-75% +30%
Code review pass rate 60% 85% +25%
Online bug rate 15% 5% -67%
Documentation timeliness 30% 95% +217%
Code compliance 70% 95% +36%

Forward-Thinking Design: Code-as-Documentation

Core Philosophy

“Code-as-Documentation” isn’t just “code includes comments”, but metadata-driven full automatic synchronization of code, documentation, testing, and routing.

httpdispatcher + make doc Innovation

In HotelByte project, we built a unique “code-as-documentation” system:

┌─────────────────────────────────────────────────────────────┐
│              Developer writes code with metadata            │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│         AST Parsing (build/api/asthelper/)                  │
└─────────────────────────────────────────────────────────────┘
                           ↓
        ┌──────────────────┴──────────────────┐
        ↓                                      ↓
┌──────────────────────┐        ┌──────────────────────┐
│   httpdispatcher     │        │    make doc         │
│  Routing + Governance │        │   Doc Generation    │
└──────────────────────┘        └──────────────────────┘
        ↓                                      ↓
┌──────────────────────┐        ┌──────────────────────┐
│  Runtime routing     │        │  OpenAPI docs        │
│  Parameter parsing   │        │  Public/Internal     │
│  Rate limiting       │        │  Multi-language      │
│  Cache configuration │        │  SDK generation      │
└──────────────────────┘        └──────────────────────┘

Impact on AI Coding

1. Reducing Boilerplate Code

Before (manual documentation):

// Business code
func (s *OrderService) GetOrder(...) {...}

// Documentation code (manual maintenance, easy to become outdated)
var orderDocs = []api.Doc{
    {
        Path: "/order/{orderId}",
        Method: "GET",
        Summary: "Get order information",
        // ... more fields
    },
}

Now (auto-generated):

// Just add metadata comments
// @jwt
// @permission:order:read
// @tags:order
// @param:orderID string "Order ID"
func (s *OrderService) GetOrder(ctx context.Context, req *GetOrderRequest) (*GetOrderResponse, error) {
    // Business logic
}

// Documentation auto-generated, zero maintenance cost, always synced with code

Code reduction: 80%

2. Consistency Guarantee

Consistency Guarantee: 100%

Scenario Manual Maintenance Auto Generation
Add parameter Modify code + modify docs (often forgotten) Only modify code, docs auto-update
Delete field Modify code + modify docs Only modify code, docs auto-update
Modify type Modify code + modify docs Only modify code, docs auto-update
Modify validation rules Modify code + modify docs + modify routing config Only modify code, others auto-update

Actual Effect Data

Metric Manual Maintenance Code-as-Documentation Improvement
Documentation maintenance time 4-6 hours/week 0 hours/week 100%
Documentation accuracy 60-70% 100% +40%
API change sync delay 2-3 days Real-time Instant
Multi-language doc maintenance 8-10 hours/week 0 hours/week 100%
SDK generation time Manual 2-3 days Auto 5 minutes 99%

Test Coverage Standards

Mandatory Checks

PR mandatory check: Incremental code test coverage must ≥ 50%

Layered Coverage Goals

Layer Coverage Goal Reason
domain/ 100% Core business logic, must be fully tested
mysql/ (DAO) 80%+ Database operations, most scenarios need testing
service/ 70%+ Business services, core flows need testing
convert/ 90%+ Conversion functions, simple but need full coverage
protocol/ Not required Pure data structures, no tests needed

Actual Coverage Data

hotel/user/domain/       100% ✅
hotel/user/mysql/         85% ✅
hotel/user/service/       78% ✅
hotel/order/domain/       100% ✅
hotel/order/mysql/         82% ✅
hotel/order/service/       75% ✅
hotel/trade/domain/       100% ✅
hotel/trade/mysql/         79% ✅
hotel/trade/service/       72% ✅

Overall coverage: 76% ✅
Incremental coverage: 62% ✅ (Target: 50%)

Code Quality Standards

Coding Standards (Zero Tolerance)

Refer to .github/code_review_rules.md, strictly enforced:

1. Logging Standards

// ❌ Wrong: Use fmt.Printf
fmt.Printf("User logged in: %s\n", username)

// ✅ Correct: Use unified logging
log.Info("User logged in", log.Field("username", username))

2. JSON Processing

// ❌ Wrong: Use json.Marshal
data, err := json.Marshal(user)

// ✅ Correct: Use utils.ToJSON
data, err := utils.ToJSON(user)

3. ID Generation

// ❌ Wrong: Manual ID generation
userID := time.Now().Unix()

// ✅ Correct: Use idgen
userID := idgen.GenID()

Lessons Learned

Key Lessons

1. Context is More Important Than Code

Wrong Approach:

User: Help me write an order query API
AI: (Generates generic code, doesn't meet project standards)

Correct Approach:

User: Use .cursor/skills/supplier-onboarding skill to generate code for order query API
AI: (Understands project standards, generates compliant code)

2. Process is More Important Than Tools

Wrong Approach:

Rely on AI "magic", no standardized process
→ Unstable code quality
→ Inconsistent team member usage
→ No knowledge accumulation

Correct Approach:

Establish OpenSpec workflow
→ All changes have clear specifications
→ Consistent process, predictable results
→ Knowledge accumulated in spec files

3. Testing is Essential, Not Optional

Wrong Approach:

AI generates code → manually test → submit
→ Frequent online bugs
→ High maintenance cost

Correct Approach:

AI generates code + tests → run tests → coverage check → submit
→ Online bug rate reduced by 67%
→ Low maintenance cost

4. Quality Cannot Be Compromised

Wrong Approach:

Lower test coverage requirements for speed
→ Short-term fast, long-term slow
→ Technical debt accumulation

Correct Approach:

Strictly enforce quality standards
→ No merge if coverage < 50%
→ No merge if code review not approved
→ No merge if tests not passing
→ Higher long-term efficiency

Best Practices Checklist

Before Development

  • Read openspec/AGENTS.md
  • Check for related OpenSpec changes
  • Choose appropriate AI model
  • Prepare project context

During Development

  • Follow DDD architecture (domain → protocol → mysql → service)
  • Add metadata comments (httpdispatcher compatible)
  • Write unit tests
  • Write E2E tests (core scenarios)

After Development

  • Run make test to check unit tests
  • Run make test-coverage to check coverage
  • Run make doc to generate documentation
  • Run AI code review (KIMI2)
  • Human code review
  • Submit PR

After Deployment

  • Monitor online metrics
  • Collect feedback
  • openspec archive
  • Update documentation and knowledge base

Future Roadmap

Short-term Goals (1-3 months)

  • Improve httpdispatcher features
    • Support more metadata tags
    • Optimize doc generation speed
    • Enhance error messages
  • Expand AI agents
    • Add performance optimization expert
    • Add security audit expert
    • Add database optimization expert

Medium-term Goals (3-6 months)

  • Project-specific model fine-tuning
    • Collect project data
    • Train custom models
    • Evaluate effectiveness
  • Automated test generation
    • Auto-generate tests from specs
    • Intelligent test case recommendation
    • Test coverage optimization suggestions

Long-term Goals (6-12 months)

  • Fully automated development workflow
    • Full automation from requirements to deployment
    • AI autonomous decision-making
    • Human only responsible for review
  • Multimodal AI integration
    • Image recognition (UI design)
    • Voice interaction (requirement input)
    • Video analysis (operation guides)

Summary

Core Value

  1. 3.5x efficiency improvement: From 5-7 days to 1-2 days
  2. 55% cost reduction: From $15,000/month to $6,800/month
  3. 30% quality improvement: Test coverage from 40-50% to 65-75%
  4. 100% documentation sync: Code-as-documentation, zero maintenance cost

Key Innovations

  1. OpenSpec workflow: Spec-driven development, quality first
  2. Multi-model smart routing: Cost optimization, performance balance
  3. httpdispatcher + make doc: Code-as-documentation, forward-thinking design
  4. Complete testing system: Mandatory coverage checks, quality assurance

Recommendations for Readers

  1. Start simple: Don’t pursue perfection initially, establish basic processes first
  2. Value specifications: Processes and specifications are more important than tools
  3. Continuous optimization: Adjust based on actual situation, don’t be rigid
  4. Knowledge accumulation: Record lessons learned, continuously improve

Series Navigation

  1. From DeepSeek Copy-Paste to Claude Code
  2. Deep Claude Code Integration
  3. Multi-Model and Toolchain Integration
  4. OpenSpec-Driven Development
  5. AI Coding Best Practices ✅ (This article)

Related Resources: