← Back to all guides

AI Tests and Docs: A 20-Minute Developer Workflow

AI can draft tests and documentation quickly. The harder part is making those drafts trustworthy. This quick-start workflow keeps you in control: define the contract, generate focused tests, check their behavior, and write documentation from verified examples. Start with one small function rather than an entire repository.

1. Give the AI a contract, not just code

Choose a function with clear inputs and outputs. For example, suppose tags.py contains normalize_tags(tags: list[str]), which cleans labels before storage. Spend two minutes writing its intended behavior:

• Accept a list of strings; reject other container types with TypeError.
• Strip surrounding whitespace, apply Python's str.casefold(), and discard empty results.
• Remove duplicates and return a new list sorted using Python's default string ordering.
• Raise TypeError if any element is not a string.
• Leave the original list unchanged.

Provide the function, this contract, your Python version, and your existing test conventions. Include relevant dependencies, but exclude secrets, customer records, and unrelated repository files. State the intended behavior separately from the implementation, or the model may simply encode existing bugs as expectations.

2. Generate a small, reviewable test suite

Use a constrained prompt rather than asking for comprehensive tests:

Prompt: “Write unittest tests for normalize_tags in tags.py using the contract below. Cover normal input, empty input, whitespace-only strings, duplicates after normalization, Unicode case folding, invalid containers, invalid elements, and input immutability. Do not change production code or install dependencies. Use explicit expected results, not a second implementation of the function. Return tests/test_tags.py and identify any ambiguous requirements.”

Review the expected values yourself. For example, [' API ', 'api', 'Docs', ' '] should become ['api', 'docs']. Unicode case folding should also make ['Straße', 'STRASSE'] become ['strasse']. An empty list should produce an empty list.

Reject tests that merely assert the result exists, mock the function under test, or reproduce its algorithm to calculate expected output. Useful tests make a specific claim about externally observable behavior.

3. Run tests, then prove they can fail

Save the generated file and run python -m unittest discover -s tests -p 'test_*.py'. If a test fails, compare the implementation and assertion against the contract before asking the AI to fix anything. A failing generated test is not automatically evidence of a production bug.

Next, temporarily remove deduplication or replace casefold() with lower(). Run the suite again: the corresponding behavior should fail. Restore the implementation immediately afterward and confirm everything passes. This lightweight mutation check exposes tests that execute code without protecting its behavior.

Ask for a second review focused on missing assertions, especially whether the original input remains unchanged. Treat coverage as a navigation aid, not proof of correctness.

4. Generate documentation from verified examples

Once the suite passes, give the AI the contract, implementation, and reviewed tests. Request a concise docstring and README section covering parameters, return values, exceptions, normalization rules, and two examples. Explicitly forbid undocumented promises about performance, locale-aware sorting, or accepted input types.

Reuse the verified examples above. If you request doctest-style examples, run python -m doctest -v tags.py after adding them to the module. Check that exception descriptions match actual behavior and that documentation explains case folding rather than vaguely promising “lowercase tags.”

5. Keep the AI loop inexpensive with 59API

59API offers low-cost, pay-as-you-go access to multiple AI providers through https://api.59api.com, with native official-quality models and no model downgrades. It works with Claude Code, Codex, Gemini CLI, and OpenAI SDKs, so you can keep your existing workflow.

Try Gemini 2.5 Flash for a first draft and Claude Sonnet 5.5 for a targeted review. Compare accepted output and total request cost on the same task; no model name guarantees better tests. Send only the relevant function and contract, cap output length, and request focused revisions instead of regenerating everything.

If this fits your workflow, sign up for 59API and trial it on one small module. Before merging, require passing tests, executable documentation examples, and a human review of every behavioral claim.

Pricing · Docs