AI Coding Assistant in Practice: Building a Navigation Website from Scratch

1. Why a Navigation Site Is a Good First Project for an AI Coding Assistant

In today’s development practice, AI coding assistants have evolved from “completing the current line” into coding agents that understand an entire project, modify files across the codebase, and execute commands autonomously. The harder question is how to tell whether an assistant is genuinely good. You need a vehicle with a clear requirement boundary, a complete technical chain, and fast visible results.

A navigation site satisfies all three:

• Clear requirement boundary: essentially “categories + links + search,” with no ambiguous business rules.
• Complete technical chain: front-end rendering, data modeling, retrieval, static asset optimization, hosting, and DNS — it touches every full-stack layer.
• Short feedback loop: when the data set is small, a static page plus a single configuration file is enough to go live.

Put differently, it doesn’t leave the assistant to “improvise” from a vague brief, and it isn’t so trivial that engineering problems never surface. Below is the breakdown, following a complete delivery flow.

2. Step 1: Write the Requirements as an Executable Spec

Most AI-assisted development fails not because of model capability but because the input requirement is too vague. “Build a navigation site” leaves the assistant guessing. “Build a single-page static site with a category sidebar, instant keyword filtering, data loaded from a local JSON file, and no backend dependency” is an executable spec.

A sound spec has four parts:

1. Product goal: one sentence on who the site is for and what problem it solves.
2. Feature list with priorities: separate the MVP (must-have) from later iterations.
3. Technical constraints: backend allowed or not, third-party dependencies allowed or not, target runtime environment.
4. Acceptance criteria: conditions that can be judged automatically, for example “filter completes within 100ms of typing a keyword” or “adding a category requires only a data file change, no code changes.”

For a navigation site, the MVP can be narrowed to:

• Data-driven: categories, site names, descriptions, URLs, icons, and tags all come from a data file.
• A top search box with case-insensitive matching across name, description, and tags.
• Category switching plus an “All” view.
• External link navigation with basic accessibility support.
• A one-command build and deploy script.

3. Step 2: Give the Agent a Stable Engineering Context

The quality of a coding agent’s output depends heavily on context quality. Three things are worth fixing at the moment you create the repository.

1. Directory conventions. Tell the assistant where each file belongs so it stops guessing:

/site
  /data        # site data (the single source of truth)
  /src         # page logic and styles
  /scripts     # build, validation, index generation
  /dist        # build output (generated by scripts, never hand-edited)
  AGENTS.md    # engineering rules

2. A rules file. Put an assistant-facing document at the repository root that states the technology choices, coding standards, and prohibited actions. For example: “no unreviewed third-party dependencies,” “all user-visible text must be HTML-escaped,” “the validation script must pass before any commit.”

3. Sample data. Three to five records with the real structure beat ten paragraphs of description — the assistant can align directly on field names and nesting.

The value here is straightforward: the more stable the context, the more consistent each round of changes becomes, and the rework rate drops noticeably.

4. Step 3: Model the Data So Content Stays Decoupled from Code

The core asset of a navigation site is data, not code. Keeping data in a structured configuration file lets non-developers maintain it and keeps the blast radius of the assistant’s changes controllable.

A minimal, extensible model:

{
  "categories": [
    { "id": "dev", "name": "Development Tools", "order": 1 }
  ],
  "sites": [
    {
      "id": "s001",
      "name": "Example Site",
      "url": "https://example.com",
      "desc": "One sentence describing the problem this site solves",
      "categoryId": "dev",
      "tags": ["docs", "search"],
      "icon": "icon/s001.svg"
    }
  ]
}

Three modeling practices worth holding to:

• Separate categories from entries, linked by categoryId, so category names aren’t repeated in every record.
• Keep id stable, since it serves as the primary key for icon filenames, cache keys, and analytics dimensions.
• Localize icons: never hot-link icons to a third-party origin. Once that origin rate-limits or changes paths, every icon on the site breaks at once — the most common outage source for navigation sites.

5. Step 4: Implementation Details for the Core Features

5.1 Retrieval logic

When the data set is under a few thousand entries, the simplest and fastest approach is to compile the data into an index at build time and filter it in memory at runtime. The filtering logic in pseudocode:

function filter(sites, keyword, categoryId):
    kw = normalize(keyword)          # trim whitespace, lowercase
    result = []
    for site in sites:
        if categoryId != "all" and site.categoryId != categoryId:
            continue
        if kw == "" or matches(site, kw):
            result.append(site)
    return result
function matches(site, kw):
    haystack = normalize(site.name + " " + site.desc + " " + join(site.tags))
    return indexOf(haystack, kw) >= 0     # can be extended with pinyin/initial-letter mapping

Once the entry count reaches the tens of thousands, or you need Chinese word segmentation and pinyin-initial matching, push retrieval to the server: a serverless function accepts query parameters, performs the match server-side, and returns only the result fragment. That’s a clean performance evolution path — there’s no need to start with a heavy search stack.

5.2 Make the agent produce tests, not just code

Even a simple navigation site has behavior worth locking down. Ask the assistant to deliver automated tests alongside the implementation, covering:

• Correctness of keyword filtering (empty keyword, mixed case, and no results).
• Consistency between category switching and URL parameters.
• Build-time data validation: a missing required field, a categoryId pointing at a nonexistent category, an invalid URL format, or a duplicate id should all fail the build outright.

The validation script matters most — it stops “bad data” incidents, the most likely production problem, at build time.

5.3 Security details that get overlooked

• External link attributes: links that open in a new window need rel="noopener noreferrer", so the target page can’t tamper with the origin page through a window reference.
• Text escaping: site names and descriptions are externally entered content and must be escaped before rendering to prevent script injection.
• Auth and rate limiting on the backend: if you expose an online submission entry point, it must have identity checks, submission rate limits, and input length caps — otherwise it’s an open spam-writing endpoint.
• Protocol validation: only allow addresses starting with https, to keep unexpected protocols out of the data.

6. Step 5: Performance and Experience Optimization

The experience of a navigation site depends almost entirely on first-load speed, which makes the optimization targets clear:

• Asset size first: merge and minify styles and scripts; don’t pull in a large framework for a search box.
• Icon strategy: prefer vector icons; normalize bitmap sizes and compress them; lazy-load icons below the fold.
• Preconnect: establish connections early for frequently visited target domains to shorten the wait after a click.
• Layered caching: use content-hash filenames for data and index files with long cache lifetimes, and a short cache for the page entry so releases take effect immediately.
• Accessibility: labeled search input, keyboard-operable category buttons, alt text on icons, and sufficient color contrast — these are compliance requirements, and they also make the quality of the agent’s generated code measurable.

7. Step 6: Deployment and Operations

The simplest architecture for a fully static navigation site is: build output → object storage → CDN → custom domain. Object storage holds the files, the CDN handles acceleration and origin fetch, DNS points at the CDN entry point, and the HTTPS certificate is configured at the edge layer. If you need online submissions, traffic analytics, or an admin backend, layer serverless functions and a managed database on top rather than maintaining a long-running server for lightweight needs.

Before launch, lock down a pipeline:

1. Pull the code → 2. Install dependencies → 3. Run data validation and unit tests → 4. Build → 5. Upload the output to object storage → 6. Invalidate the CDN cache → 7. Health check and release decision.

Don’t run operations bare-handed:

• Monitoring and alerting: availability probes, CDN hit rate, error rate, and latency of core endpoints.
• Logging service: centralized collection of access logs and function execution logs to help track down intermittent failures.
• Backups: keeping the data files in version control is already the most reliable backup, since the build output can always be regenerated.

8. Common Pitfalls and an Acceptance Checklist

Pitfall	Consequence	Mitigation
Hot-linking icons from third parties	Remote rate limiting breaks every icon on the site	Localize all icons
Data coupled to rendering	Adding a link requires a code change	Data file as the single source of truth
No build-time validation	Bad data ships to production	Fail the build on validation errors
One large sweeping change	Agent misunderstandings get amplified	Slice work into the smallest tasks
Generating without verifying	Hidden defects carry over	Run tests and manual acceptance in parallel

At acceptance, confirm each item: data can be maintained incrementally, empty search results show a clear message, the mobile layout works, external link attributes are complete, and both build and rollback can be repeated.

9. Conclusion

The quality of an AI coding assistant’s output comes down to how clear the engineering constraints are. The general takeaway from this navigation site project: define the spec, directory conventions, data model, and acceptance criteria first; then hand the implementation to the assistant while the human reviews and provides the safety net. When data is decoupled from code, validation is shifted left into the build, and the deployment chain is repeatable, the delivered result stays stable regardless of which coding agent you switch to.

The next steps build naturally on this foundation: multi-language support, personalized ordering, traffic analytics, or turning submissions into a workflow with review — each one can proceed within the boundaries defined in this article.